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Production Note 


This book was produced with the VAX DOCUMENT electronic publishing 
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document. Writers can print the document on the terminal or line printer, 
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and PostScript printers (PrintServer 40 or LNO3R ScriptPrinter), to 
produce a typeset-quality copy containing integrated graphics. 
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Preface 


Intended Audience 


This manual is intended for programmers who want to invoke and 
manipulate VMS utilities from a program. 


Document Structure 
This document contains the following chapters. 


Chapter 1 introduces the utility routines and describes the documentation 
format used to describe each set of utility routines, as well as the 
individual routines in each set. Each subsequent chapter contains an 
introduction to a set of utility routines, a programming example to 
illustrate the use of the routines in the set, and a detailed description 

of each routine. 


This manual presents the utility routine sets as follows: 

¢ Chapter 2 — ACL Editor routine. 

¢ Chapter 3 — Command Language (CLI) routines 

e Chapter 4 — Convert (CONV) routines 

e Chapter 5 — Data Compression/Expansion routines 

¢ Chapter 6 — EDT Editor routines 

e Chapter 7 — File Definition Language (FDL) routines 

¢ Chapter 8 — Librarian (LBR) routines 

¢ Chapter 9 — Mail routines 

e Chapter 10 — National Character Set (NCS) Utility routines 

e Chapter 11 — Print Symbiont Modification (PSM) routines 

¢ Chapter 12 — Symbiont/Job Controller Interface (SMB) routines 
¢ Chapter 13 — Sort/Merge (SOR) routines 

e Chapter 14 — VAX Text Processing Utility (VAXTPU) routines 





Associated Documents 


The VAX Procedure Calling and Condition Handling Standard, which 

is documented in the Introduction to VMS System Routines, contains 
useful information for all programmers. The Introduction to VMS System 
Routines also describes in detail the documentation format of the routine 
descriptions. 
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Preface 


Some sets of utility routines documented in this manual invoke and 
manipulate utilities that have a command level interface. Consult the 
following manuals for a description of the command level interface: 


¢ VMS Access Control List Editor Manual 

¢ VMS Command Definition Utility Manual 

¢ VMS Convert and Convert/Reclaim Utility Manual 
© VAX EDT Reference Manual 

e VMS File Definition Language Facility Manual 

¢ VMS Librarian Utility Manual 

¢ VMS Mail Utility Manual 

¢ VMS Sort/Merge Utility Manual 

° VAX Text Processing Utility Manual 

¢ VMS National Character Set Utility Manual 





Conventions 


xviii 


The documentation template for utility routines, which is described in the 
Introduction to VMS System Routines, details the conventions used in this 
manual, as well as the organizational approach used to document each 
utility routine. 


The following table describes additional conventions that appear in this 
manual: 


Convention Meaning 


Ctri/x A sequence such as Cirl/x indicates that you must 
hold down the key labeled Ctrl while you press 
another key or a pointing device button. 


PF1 x A sequence such as PF1 x indicates that you must 
first press and release the key labeled PF1, then 
press and release another key or a pointing device 
button. 


In examples, a key name is shown enclosed in 
a box to indicate that you press a key on the 
keyboard. (In text, a key name is not enclosed in a 
box.) 


in examples, a horizontal ellipsis indicates one of 
the following possibilities: 


¢ Additional optional arguments in a statement 
have been omitted. 

¢ The preceding item or items can be repeated 
one or more times. 

* Additional parameters, values, or other 
information can be entered. 
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Convention 


{] 


{} 


red ink 


boldface text 


italic text 


UPPERCASE TEXT 


numbers 


Meaning 


A vertical ellipsis indicates the omission of items 
from a code example or command format; the 
items are omitted because they are not important 
to the topic being discussed. 


In format descriptions, parentheses indicate that, 
if you choose more than one option, you must 
enclose the choices in parentheses. 


In format descriptions, brackets indicate that 
whatever is enclosed within the brackets is 
optional; you can select none, one, or all of the 
choices. (Brackets are not, however, optional in 
the syntax of a directory name in a file specification 
or in the syntax of a substring specification in an 
assignment statement.) 


In format descriptions, braces surround a required 
choice of options; you must choose one of the 
options listed. 


Red ink indicates information that you must enter 
from the keyboard or a screen object that you must 
choose or click on. 


For online versions of the book, user input is 
shown in bold. 


Boldface text represents the introduction of a new 
term or the name of an argument, an attribute, or a 
reason. 


Boldface text is also used to show user input in 
online versions of the book. 


Italic text represents information that can vary 
in system messages (for example, Internal error 
number). 


Uppercase letters indicate that you must enter a 
command (for example, enter OPEN/READ), or 

they indicate the name of a routine, the name of 
a file, the name of a file protection code, or the 

abbreviation for a system privilege. 


Hyphens in coding examples indicate that 
additional arguments to the request are provided 
on the line that follows. 


Unless otherwise noted, all numbers in the text are 
assumed to be decimal. Nondecimal radixes— 
binary, octal, or hexadecimal—are explicitly 
indicated. 


xix 





1 Introduction to Utility Routines 


A set of utility routines performs a particular task or set of tasks. For 
example, you can use the Print Symbiont Modification (PSM) routines to 
modify the VMS print symbiont, and the EDT routines to invoke the EDT 
editor from a program. 


Some of the tasks performed by utility routines can also be performed 

at the DIGITAL Command Language (DCL) level (for example, the DCL 
command EDIT invokes the EDT editor). While DCL commands invoke 
VMS utilities that allow you to perform tasks at your terminal, you can 
perform some of these tasks at the programming level through the use of 
the utility routines. 


When using a set of utility routines that performs the same tasks as a 
VMS utility, you should read the documentation for that utility; doing 
so will provide additional information about the tasks the routines 
can perform as a set. The following table lists VMS utilities and their 
corresponding routines: 


Utility or Editor Utility Routines 
Access Control List Editor ACL Editor routine 
Command Definition Utility CLI routines 
Convert and Convert/Reclaim Utilities CONV routines 
EDT Editor EDT routines 

File Definition Language Facility FDL routines 
Library Utility LBR routines 
MAIL Mail routines 
VMS National Character Set Utility NCS routines 
Sort/Merge Utility SOR routines 
VAX Text Processing Utility VAXTPU routines 


When a set of utility routines performs functions that you cannot perform 
by invoking a VMS utility, the functions provided by that set of routines ‘is 
termed a facility. The following facilities have no other user interface 
except the programming interface provided by the utility routines 
described in this manual: 


Facility Utility Routines 
Data Compression/Expansion Facility DCX routines 
Print Symbiont Modification Facility PSM routines 
Symbiont/Job-Conitroller Interface Facility SMB routines 
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Introduction to Utility Routines 


The utility routines described in this manual are called in the same way 
as all other system routines in the VMS operating system environment, 
which is to say that utility routines conform to the VAX Procedure Calling 
and Condition Handling Standard. 


Each chapter of this book documents one set of utility routines. Each 
chapter has the following major components, documented as a major 
heading: 


¢ An introduction to the set of utility routines. This component discusses 
the utility routines as a group and explains how to use them. 


¢ A series of descriptions of each utility routine in the set. 


Most of the chapters also include a programming example that illustrates 
how the utility routines are used. 


2 


2.1 


Access Control List (ACL) Editor Routine 


This chapter describes the Access Control List (ACL) Editor routine, 
ACLEDIT$EDIT. User-written applications can use this callable interface 
of the ACL Editor to manipulate Access Control Lists. 


The ACL Editor is a VMS utility that lets you create and maintain access 
control lists. Using ACLs, you can fine-tune the type of access to files, 
devices, global sections, logical name tables, or mailboxes available to 
system users. 


Currently, the ACL Editor provides one callable interface that allows the 
application program to define an object for editing. 


Note that the application program should declare referenced constants and 
return status symbols as external symbols; these symbols will be resolved 
upon linking with the utility shareable image. 


See Introduction to VMS System Services for fundamental conceptual 
information on the creation, translation, and maintenance of ACEs. 


Using the ACL Editor Routine: An Example 
Example 2—1 shows a VAX BLISS program that calls the ACL Editor 
routine. 


Example 2-1 Calling the ACL Editor with a VAX BLISS Program 


MODULE MAIN (LANGUAGE (BLISS32), MAIN = STARTUP) = 
BEGIN 

LIBRARY ’SYSS$LIBRARY:LIB’ ; 

ROUTINE STARTUP = 

BEGIN 


LOCAL 
STATUS, ! Routine return status 
ITMLST : BLOCKVECTOR [6, ITMSS_ITEM, BYTE]; 
! ACL editor item list 


EXTERNAL LITERAL 
ACLEDIT$V_JOURNAL, 
ACLEDIT$V_PROMPT_MODE, 


ACLEDITSC_OBJNAM, 
ACLEDITSC_OBJUTYP, 
ACLEDITSC_OPTIONS; 


EXTERNAL ROUTINE 
ACLEDITSEDIT : ADDRESSING MODE (GENERAL), ! Main routine 


(continued on next page) 
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Access Control List (ACL) Editor Routine 
2.1 Using the ACL Editor Routine: An Example 


Example 2-1 (Cont.) Calling the ACL Editor with a VAX BLISS Program 





CLISGET_VALUE, ! Get qualifier value 
CLISPRESENT, ! See if qualifier present 
LIBSPUT_OUTPUT, ! General output routine 
STRSCOPY_DX; ! Copy string by descriptor 


! Set up the item list to pass back to TPU so it can figure out what to do. 


CHSFILL (0, 6*ITM$S_ ITEM, ITMLST) ; 

ITMLST[O, ITMS$W_ITMCOD] = ACLEDITSC_OBJNAM; 

ITMLST[0, ITMSW_BUFSIZ] SCHARCOUNT (’ YOUR_OBJECT_NAME’ ) ; 

ITMLST[(0, ITM$L_BUFADR] $DESCRIPTOR (’ YOUR_OBJECT_NAMB’ ) ; 

ITMLST(1, ITMSW_ITMCOD] = ACLEDIT$C_OBJTYP; 

ITMLST[(1, ITM$W_BUFSIZ] 4; 

ITMLST(1, ITM$L_BUFADR] = UPLIT (ACLS$C_FILE) ; 

ITMLST(2, ITMSW_ITMCOD] ACLEDITS$C_OPTIONS; 

ITMLST[2, ITMSW_BUFSIZ] 4; 

ITMLST[2, ITM$L_BUFADR] = UPLIT (1 * ACLEDIT$V_PROMPT_MODE OR 
1 * ACLEDIT$V_JOURNAL) ; 


| 


RETURN ACLEDITSEDIT (ITMLST) ; 





END; ! End of routine STARTUP 
END 

ELUDOM 

ACL Editor Routine 


The following pages describe the ACL Editor routine. 
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Access Control List (ACL) Editor Routine 
ACLEDITSEDIT 


ACLEDITSEDIT Edit Access Control List 


The ACLEDIT$EDIT routine is used to create and modify an Access Control 
List (ACL) associated with any system object. 





FORMAT 


ACLEDIT$EDIT item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


item_list 

VMS usage: item_list_3 

type: longword (unsigned) 

access: read only 

mechanism: by descriptor 

Item list used by the callable ACL Editor. The item_list argument is the 
address of one or more descriptors of arrays, routines, or longword bit 
masks that control various aspects of the editing session. 


Each entry in an item list is in the standard format shown in the following 
figure. 


Buffer Address 
Return Length Address 


ZK-5012-GE 














Following is a detailed description of each item list entry. 


Item Identifier Description 

ACLEDIT$C_OBJNAM Specifies the name of the object whose ACL is being 
edited. 

ACLEDIT$C_OBJTYP Specifies the type of the object whose ACL is being 


edited. These type codes are defined in $ACLDEF. The 
default object type is a file (ACL$C_FILE). 
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Access Control List (ACL) Editor Routine 
ACLEDITS$EDIT 


Item Identifier Description 
ACLEDIT$C_OPTIONS Represents a longword bit mask of the various options 


available to control the editing session. 


Flag 
ACLEDIT$V_JOURNAL 


ACLEDIT$V_RECOVER 


ACLEDIT$V_KEEP_RECOVER 


ACLEDIT$V_KEEP_JOURNAL 


ACLEDIT$V_PROMPT_MODE 


Function 


Indicates that the 
editing session is 
to be journaled. 


Indicates that the 
editing session is 
to be recovered 
from an existing 
journal file. 


Indicates that the 
journal file used to 
recover the editing 
session is not to 
be deleted when 
the recovery is 
complete. 


Indicates that the 
journal file used 
for the editing 
session is not to 
be deleted when 
the session ends. 


Indicates that 

the session is to 
use automatic 
text insertion 
(prompting) to 
build new access 
conirol list entries 
(ACEs). 


ACLEDIT$C_BIT_TABLE Specifies a vector of 32 quadword string descriptors 
of strings which define the names of the bits present 
in the access mask. (The first descriptor defines the 
name of Bit 0; the last descriptor defines the name 
of Bit 31.) These descriptors are used in parsing or 
formatting an ACE. The buffer address field of the item 
descriptor contains the address of this vector. 





DESCRIPTION You use the ACLEDIT$EDIT routine to create and modify an ACL 


associated with any system object. 


Under normal circumstances, the application calls the ACL Editor to 
modify an object’s ACL, and control is returned to the application when 


you finish or abort the editing session. 
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Access Control List (ACL) Editor Routine 
ACLEDIT$EDIT 


If you also want to use a customized version of the ACL Editor section 
file, the logical name ACLEDT$SECTION should be defined. See the VMS 
Access Control List Editor Manual for more information. 





CONDITION 
SS$_NORMAL Normal successful completion. 
VALUES 
RMS$_xxx See the VMS Record Management Services Manual 
RETURNED for a description of RMS status codes. 
TPU$_xxx See Chapter 14 for a description of the TPU- 
specific condition values that may be returned by 
ACLEDIT$EDIT. 
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3 Command Language (CLI) Routines 


You use the CLI routines to process command strings using information 
from a command table. A command table contains command definitions 
that describe the allowable formats for commands. To create or modify a 
command table, you must write a command definition file and then process 
this file with the Command Definition Utility (the SET COMMAND 
command). For information about how to use the Command Definition 
Utility, see the VMS Command Definition Utility Manual. 


3.1 Introduction to CLI Routines 
The CLI routines include the following: 
¢ CLI$DCL_PARSE 
¢ CLI$DISPATCH 
¢ CLI$GET_VALUE 
¢ CLI$PRESENT 


When you use the Command Definition Utility to add a new command 
to your process command table or to the DCL command table, use the 
CLI$PRESENT and CLI$GET_VALUE routines in the program invoked 
by the new command. These routines retrieve information about the 
command string that invokes the program. 


When you use the Command Definition Utility to create an object module 
containing a command table and you link this module with a program, 
you must use all four CLI routines. First, use CLI$DCL_PARSE and 
CLI$DISPATCH to parse command strings and invoke routines. Then, use 
CLI$PRESENT and CLI$GET_VALUE within the routines that execute 
each command. 


Note that the application program should declare referenced contants and 
return status symbols as external symbols; these symbols are resolved 
upon linking with utility shareable image. 


A CLI must be present in order to use the CLI routines. If your application 
might be run from a detached process, then the application should check 
to verify that a CLI exists. For information about how to determine if a 
CLI exists for a process, see the description of the SYS$¢GETJPI system 
service in the VMS System Services Reference Manual. 
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Command Language (CLI) Routines 
3.2 Using the CLI Routines:An Example 


3.2 Using the CLI Routines:An Example 
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Example 3-1 contains a command definition file (SUBCOMMANDS.CLD) 
and a FORTRAN program (INCOME.FOR). INCOME.FOR uses the 
command definitions in SUBCOMMANDS.CLD to process commands. To 
execute the example, enter the following commands: 


$ SET COMMAND SUBCOMMANDS/OBJECT=SUBCOMMANDS 
$ FORTRAN INCOME 

$ LINK INCOME, SUBCOMMANDS 

$ RUN INCOME 


INCOME.FOR accepts a command string and parses it using 
CLI$DCL_PARSE. If the command string is valid, the program 

uses CLI$DISPATCH to execute the command. Each routine uses 
CLI$PRESENT and CLI$GET_VALUE to obtain information about the 
command string. 


a 


Command Language (CLI) Routines 
3.2 Using the CLI Routines:An Example 


Example 3-1 Using the CLI Routines to Retrieve Information About 
Command Lines in a FORTRAN Program 





KKK KKK KKK KKK KK KKK KKK KKK KR KKK KERR KEKE KR RRR ERK EKER REE K 
SUBCOMMANDS. CLD 


KRKEKKKKKKKKKKEKKKRKKKEKKKKKR KEK KEK EKER KRKEKKKEKKKKKKKKKKKKKEK 


MODULE INCOME SUBCOMMANDS 


DEFINE VERB ENTER 
ROUTINE ENTER 


DEFINE VERB FIX 
ROUTINE FIX 
QUALIFIER HOUSE NUMBERS, VALUE (LIST) 


DEFINE VERB REPORT 

ROUTINE REPORT 

QUALIFIER OUTPUT, VALUE (TYPE = $FILE, 
DEFAULT = "“INCOME.RPT") 
DEFAULT 


KRKEKKKKKKKKKKKKKKKKKKKEKKEKRKKKRKEKEKKKKKKKKKKEKKKKEKKKKKKK 


INCOME .FOR 
KKREKKKEKKEKKKKKKEKKRKKKEKKKKKKKKEKKKKEKEKEKKKKERKEKKEKREKKEKKEE 
PROGRAM INCOME 
INTEGER STATUS, 

2 CLI$DCL_PARSE, 

2 CLISDISPATCH 
INCLUDE ’ ($RMSDEF) ’ 

INCLUDE ’ ($STSDEF) ‘ 
EXTERNAL INCOME _SUBCOMMANDS, 
2 LIBSGET INPUT 


! Write explanatory text 

STATUS = LIBSPUT_OUTPUT 

2 (’Subcommands: ENTER - FIX - REPORT’) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
STATUS = LIBSPUT_OUTPUT 

2 (’Press CTRL/Z to exit’) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
! Get first subcommand 

STATUS = CLISDCL_PARSE (SVAL (0), 


2 INCOME _SUBCOMMANDS, ! CLD module 

2 LIBSGET_INPUT, ! Parameter routine 
2 LIBS$GET_INPUT, ! Command routine 

2 ‘INCOME> ’) ! Command prompt 


! Do it until user presses CTRL/Z 
DO WHILE (STATUS .NE. RMS$_EOF) 
! If no error on dcl_parse 
IF (STATUS) THEN 
! Dispatch depending on subcommand 
STATUS = CLISDISPATCH () 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
! Do not signal warning again 
ELSE IF (IBITS (STATUS, 0, 3) .NE. STS$K_WARNING) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 





(continued on next page) 
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Example 3-1 (Cont.) Using the CLI Routines to Retrieve Information 
About Command Lines in a FORTRAN Program 


! Get another subcommand 
STATUS = CLISDCL_PARSE (SVAL (0), 


2 INCOME _SUBCOMMANDS, ! CLD module 

2 LIBSGET_INPUT, ! Parameter routine 
2 LIB$GET_INPUT, ! Command routine 

2 “INCOME> /) ! Command prompt 
END DO 

END 


INTEGER FUNCTION ENTER () 
INCLUDE ’ ($SSDEF)’ 

TYPE *, ‘ENTER invoked’ 
ENTER = SS$_NORMAL 

END 


INTEGER FUNCTION FIX () 

INTEGER STATUS, 

2 CLISPRESENT, 

2 CLISGET_VALUE 

CHARACTER*15 HOUSE NUMBER 

INTEGER*2 HN_ SIZE 

INCLUDE ’ ($SSDEF)’ 

EXTERNAL CLI$_ ABSENT 

TYPE *, /FIX invoked’ 

! If user types /house_numbers=(n,...) 

IF (CLISPRESENT (’HOUSE_NUMBERS’)) THEN 

! Get first value for /house_numbers 
STATUS = CLISGET_VALUE (’HOUSE_NUMBERS’, : 
2 HOUSE_NUMBER, 

2 HN SIZE) 

! Do it until the list is depleted 

DO WHILE (STATUS) 

TYPE *, ‘House number = ’, HOUSE NUMBER (1:HN_ SIZE) 

STATUS = CLISGET_VALUE (’HOUSE_NUMBERS’, 


2 HOUSE_NUMBER, 
2 HN_ SIZE) 
END DO 


! Make sure termination status was correct 
IF (STATUS .NE. $LOC (CLI$_ABSENT)) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 

END IF 

END IF 

FIX = SS$_ NORMAL 

END 


aS 


INTEGER FUNCTION REPORT () 
INTEGER STATUS, 

2 CLISGET_VALUE 
CHARACTER*64 FILENAME 
INTEGER*2 FN SIZE 
INCLUDE ’ (SSSDEF) ’ 

TYPE *, ‘REPORT entered’ 





(continued on next page) 
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Example 3-1 (Cont.) Using the CLI Routines to Retrieve Information 
About Command Lines in a FORTRAN Program 


! Get value for /output 

STATUS = CLISGET_VALUE (’OUTPUT’, 

2 FILENAME, 

2 FN_SIZE) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
TYPE *, ‘Output file: ’, FILENAME (1:FN_SIZE) 
REPORT = SS$ NORMAL 

END 





3.3 CLI Routines 
The following pages describe the individual CLI routines. 
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Command Language (CLI) Routines 


CLI$DCL_PARSE 


CLISDCL_PARSE Parse DCL Command String 


The CLISDCL_PARSE routine supplies a command string to DCL for parsing. 
DCL separates the command string into its individual elements according to 
the syntax specified in the command table. 





FORMAT 


CLI$SDCL_PARSE [command_string] ,table 
[param_routine] [,prompt_routine] 
[,prompt_string] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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command_string 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor—fixed length 

Character string containing the command to be parsed. The command_ 
string argument is the address of a descriptor specifying the command 
string to be parsed. If the command string includes a comment (delimited 
by an exclamation mark), DCL ignores the comment. 


If the command string contains a hyphen to indicate that the string is 
being continued, DCL uses the routine specified in the prompt_routine 
argument to obtain the rest of the string. The command string is limited 
to 256 characters. However, if the string is continued with a hyphen, 
CLI$DCL_PARSE can prompt for additional input until the total number 
of characters is 1024. 


If you specify the command_string argument as zero and specify a 
prompt routine, then DCL prompts for the entire command string. 
However, if you specify the command_string argument as zero and 
also specify the prompt_routine argument as zero, then DCL restores 
the parse state of the command string that originally invoked the image. 


CLI$DCL_PARSE does not perform DCL-style symbol substitution on the 
command string. 


table 

VMS usage: address 
type: address 
access: read only 


mechanism: by value 


Command Language (CLI) Routines 
CLI$DCL_PARSE 


Address of the compiled command tables to be used for command parsing. 
The command tables are compiled separately by the Command Definition 
Utility using the DCL command SET COMMAND/OBJECT, and are then 
linked with your program. A global symbol is defined by the Command 
Definition Utility that provides the address of the tables. The global 
symbol’s name is taken from the module name given on the MODULE 
statement in the command definition file, or from the file name if no 
MODULE statement is present. 


param_routine 


VMS usage: procedure 

type: procedure entry mask 

access: read only 

mechanism: by reference 

Name of a routine to obtain a required parameter not supplied in the 
command text. The param_routine argument is the address of a routine 
containing a required parameter that was not specified in the command_ 
string argument. 


To specify the parameter routine, use the address of LIB$GET_INPUT or 
the address of a routine of your own that has the same three-argument 
calling format as LIB$GET_INPUT. See the description of LIB$GET_ 
INPUT in the VMS RTL Library (LIB$) Manual for information about 
the calling format. If LIB$GET_INPUT returns error status, CLISDCL_ 
PARSE propagates the error status outward or signals RMS$_EOF in the 
cases listed in the “Description” section. 


You can obtain the prompt string for a required parameter from the 
command table specified in the table argument. 


pr ompt__ routine 

VMS usage: procedure 

type: procedure entry mask 

access: read only 

mechanism: by reference 

Name of a routine to obtain all or part of the text of a command. The 
prompt_routine argument is the address of a routine to obtain the text 
or the remaining text of the command depending on the command_string 
argument. If you specify a zero in the command_string argument, DCL 
uses this routine to obtain an entire command line. DCL uses this routine 
to obtain a continued command line if the command string (obtained from 
the command_string argument) contains a hyphen to indicate that the 
string is being continued. 


To specify the prompt routine, use the address of LIB$GET_INPUT or the 
address of a routine of your own that has the same three-argument calling 
format as LIB$GET_INPUT. See the description of LIB$GET_INPUT in 
the VMS RTL Library (LIB$) Manual for information about the calling 
format. 


If LIB$GET_INPUT returns error status, CLISDCL_PARSE propagates 
the error status outward or signals RMS$_EOF in the cases listed in the 
“Description” section. 
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prompt_string 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Character string containing a prompt. The prompt_string argument 
is the address of a string descriptor pointing to the prompt string to be 
passed as the second argument to the prompt_routine argument. 


If DCL is using the prompt routine to obtain a continuation line, DCL 
inserts an underscore character before the first character of the prompt 
string to create the continuation prompt. If DCL is using the prompt 
routine to obtain an entire command line (that is, a zero was specified as 
the command_string argument), DCL uses the prompt string exactly as 
specified. 


The prompt string is limited to 32 characters. The string COMMAND> is 
the default prompt string. 





DESCRIPTION = The CLI$DCL_PARSE routine supplies a command string to DCL for 
parsing. DCL parses the command string according to the syntax in the 
command table specified in the table argument. 


The CLI$DCL_PARSE routine can prompt for required parameters if you 
specify a parameter routine in the routine call. In addition, the CLI$DCL_ 
PARSE routine can prompt for entire or continued command lines if you 
supply the address of a prompt routine. 


If you do not specify a command string to parse and the user enters a null 
string in response to the DCL prompt for a command string, CLI$SDCL_ 
PARSE immediately terminates and returns the status RMS$_EOF. 


If DCL prompts for a required parameter and the user enters CTRL/Z, 
CLI$DCL_PARSE immediately terminates and returns the status CLI$_ 
NOCMD, regardless of whether you specify or do not specify a command 
string to parse. If DCL prompts for a parameter that is not required 
and the user enters CTRL/Z, CLI$DCL_PARSE returns the status CLI$_ 
NORMAL. 


Whenever CLI$DCL_PARSE encounters an error, it both signals and 
returns the error. 





CONDITION ets 
CLISIVVERB Invalid or missing verb. 
VALUES 
RETURNED CLI$_NORMAL Normal successful completion. 
CLI$_ NOCOMD Routine terminated. You entered a null string in 


response to a prompt from the prompt_routine 
argument, causing the CLISDCL_PARSE routine to 
terminate. 

RMS$_EOF Routine terminated. You pressed CTRL/Z in response 
to a prompt, causing the CLISDCL_PARSE routine to 
terminate. 
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CLI$DISPATCH Dispatch to Action Routine 


The CLISDISPATCH routine invokes the subroutine associated with the verb 
most recently parsed by a CLISDCL_PARSE routine call. 








FORMAT CLI$DISPATCH _[userarg] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 





ARGUMENT userarg 


VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by value 

Data to be passed to the action routine. The userarg argument is a 
longword that contains the data to be passed to the action routine. This 
data can be used in any way you want. 





DESCRIPTION The CLI$DISPATCH routine invokes the subroutine associated with the 
verb most recently parsed by a CLISDCL_PARSE routine call. If the 
routine is successfully invoked, the return status is the status returned by 
the action routine. Otherwise, a status of CLI$_INVROUT is returned. 





CONDITION . . 

V ALUE CLI$_INVROUT CLISDISPATCH unable to invoke the routine. An 
invalid routine is specified in the command table, or 

RETURNED no routine is specified. 
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CLI$GET_VALUE 


CLISGET_ VALUE Get Value of Entity in Command 


String 


The CLISGET_VALUE routine retrieves a value associated with a specified 
qualifier, parameter, keyword, or keyword path from the parsed command 
string. 





FORMAT 


CLISGET_VALUE  entity_desc ,retdesc [,retlength] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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entity_desc 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Character string containing the label (or name if no label is defined) of 
the entity. The entity_desc argument is the address of a string descriptor 
that points to an entity that may appear on a command line. The entity_ 
desc argument can be expressed as one of the following: 


e A parameter, qualifier, or keyword name or label 


e A keyword path 


The entity_dese argument can contain qualifier, parameter, or keyword 
names, or can contain labels that were assigned with the LABEL clause 
in the command definition file. If you used the LABEL clause to assign a 
label to an entity, you must specify the label in the entity_dese argument. 
Otherwise, use the name of the entity. 


You use a keyword path to reference keywords used as values of 
parameters, qualifiers, or other keywords. A keyword path contains a 
list of entity names or labels separated by periods. If the LABEL clause 
was used to assign a label to an entity, you must specify the label in the 
keyword path. Otherwise, you must use the name of the entity. 


The following command string illustrates a situation where keyword paths 
are needed to uniquely identify keywords. In this command string, you 
can use the same keywords with more than one qualifier. (This is defined 
in the command definition file by having two qualifiers refer to the same 
DEFINE TYPE statement.) 


$ NEWCOMMAND/QUAL1= (START=5, END=10) /QUAL2= (START=2, END=5) 


eS 
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The keyword path QUAL1.START identifies the START keyword when 

it is used with QUAL1; the keyword path QUAL2.START identifies the 
keyword START when it is used with QUAL2. Because the name START 
is an ambiguous reference if used alone, the keywords QUALI and QUAL2 
are needed to resolve the ambiguity. 


You can omit keywords from the beginning of a keyword path if they are 
not needed to unambiguously resolve a keyword reference. A keyword 
path can be no more than eight names long. 


If you use an ambiguous keyword reference, DCL resolves the reference by 
checking, in the following order: 


1 The parameters in your command definition file, in the order they are 
listed 


2 The qualifiers in your command definition file, in the order they are 
listed 


3 The keyword paths for each parameter, in the order the parameters 
are listed 


4 The keyword paths for each qualifier, in the order the qualifiers are 
listed 


DCL uses the first occurrence of the entity as the keyword path. Note 
that DCL does not issue an error message if you provide an ambiguous 
keyword. However, because the keyword search order may change 

in future releases of VMS, you should never use ambiguous keyword 
references. 


If the entity_desc argument does not exist in the command table, 
CLI$GET_VALUE signals a syntax error (by means of the signaling 
mechanism described in the VMS Run-Time Library Routines Volume). 


retdesc 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 

Character string containing the value retrieved by CLISGET_VALUE. 
The retdese argument is the address of a string descriptor pointing to 
the buffer to receive the string value retrieved by CLISGET_VALUE. The 
string is returned using the STR$COPY_DX VAX-11 Run-Time Library 
routine. 


If there are errors in the specification of the return descriptor or in 
copying the results using that descriptor, the STR6COPY_DX routine 
will signal the errors. For a list of these errors, see the VMS RTL String 
Manipulation (STR$) Manual. 


retlength 

VMS usage: word_unsigned 

type: word (unsigned) 

access: write only 

mechanism: by reference 

Word containing the number of characters DCL returns to retdesc. The 
retlength argument is the address of the word containing the length of 
the retrieved value. 
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The CLI$GET_VALUE routine retrieves a value associated with a specified 
DESCRIPTION 
qualifier, parameter, keyword, or keyword path from the parsed command 
string. 


You can use the following label names with CLISGET_VALUE to retrieve 
special strings: 


$VERB Describes the verb in the command string (the first four letters of the 
spelling as defined in the command table, instead of the string that was 
actually typed). 

$LINE Describes the entire command string as stored internally by DCL. In the 
internal representation of the command string, multiple spaces and tabs 
are removed, alphabetic characters are converted to uppercase, and 
comments are stripped. Integers are converted to decimal. If dates and 
times are specified in the command string, DCL fills in any defaulted fields. 
Also, if date-time strings (such as YESTERDAY) are used, DCL substitutes 
the corresponding absolute time value. 


To obtain the values for a list of entities, call CLISGET_VALUE repeatedly 
until all values have been returned. After each CLISGET_VALUE call, the 
returned condition value indicates whether there are more values to be 
obtained. You should call CLISGET_VALUE until you receive a condition 
value of CLI$_ABSENT. 


When you are using CLISGET_VALUE to obtain a list of qualifier or 
keyword values, you should get all values in the list before starting to 
parse the next entity. 





CONDITION . . 
VALUES CLI$_COMMA Returned value terminated by a comma. This shows 
there are additional values in the list. 
RETURNED CLI$_CONCAT Returned value concatenated to the next value with a 
plus sign. This shows there are additional values in 
the list. 
SS$_NORMAL Returned value terminated by a blank or an end-of- 


line. This shows that the value is the last, or only, 
value in the list. 


CLI$_ABSENT No value returned. The value is not present, or the 
last value in the list was already returned. 
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CLISPRESENT Determine Presence of Entity in 
Command String 


The CLISPRESENT routine examines the parsed command string to 
determine whether the entity referred to by the entity_desc argument is 








present. 
FORMAT CLISPRESENT entity_desc 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT entity_desc 
VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
Character string containing the label (or name if no label is defined) of 
the entity. The entity_desc argument is the address of a string descriptor 
that points to an entity that may appear on a command line. An entity 
can be expressed as one of the following: 


e A parameter, qualifier, or keyword name or label 


¢ A keyword path 


A keyword path is used to reference keywords that are accepted by 
parameters, qualifiers, or other keywords. A keyword path contains a list 
of entity names separated by periods. See the description of the entity_ 
desc argument in the CLISGET_VALUE routine for more information 
about specifying keyword paths as arguments for CLI routines. 


The entity_desc argument can contain parameter, qualifier, or keyword 
names, or can contain labels that were assigned with the LABEL clause 
in the command definition file. If the LABEL clause was used to assign a 
label to a qualifier, parameter, or keyword, you must specify the label in 
the entity_desc argument. Otherwise, you must use the actual name of 
the qualifier, parameter, or keyword. 


If the-entity_dese argument does not exist in the command table, 
CLI$PRESENT signals a syntax error (by means of the signaling 
mechanism described in the VMS Run-Time Library Routines Volume). 
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DESCRIPTION 


The CLISPRESENT routine examines the parsed command string to 
determine whether the entity referred to by the entity_dese argument is 
present. 


When CLI$PRESENT tests whether a qualifier is present, the condition 
value indicates whether the qualifier is used globally or locally. You can 
use a global qualifier anywhere in the command line; you use a local 
qualifier only after a parameter. A global qualifier is defined in the 
command definition file with PLACEMENT=GLOBAL; a local qualifier is 
defined with PLACEMENT=LOCAL. 


When you test for the presence of a global qualifier, CLISPRESENT 
determines if the qualifier is present anywhere in the command string. If 
the qualifier is present in its positive form, CLISPRESENT returns CLI$_ 
PRESENT; if the qualifier is present in its negative form, CLISPRESENT 
returns CLI$_ NEGATED. 


You can test for the presence of a local qualifier when you are parsing 
parameters that can be followed by qualifiers. After you call CLISGET_ 
VALUE to fetch the parameter value, call CLISPRESENT to determine 
whether the local qualifier is present. If the local qualifier is present in 
its positive form, CLISPRESENT returns CLI$_LOCPRES; if the local 
qualifier is present in its negative form, CLISPRESENT returns CLI$_ 
LOCNEG. 


A positional qualifier affects the entire command line if it appears after the ( 
verb but before the first parameter. A positional qualifier affects a single 
parameter if it appears after a parameter. A positional qualifier is defined 

in the command definition file with the PLACEMENT=POSITIONAL 


clause. 


aN 


To determine whether a positional qualifier is used globally, call 
CLI$PRESENT to test for the qualifier before you call CLI$SGET_VALUE 

to fetch any parameter values. If the positional qualifier is used globally, 
CLI$PRESENT returns either CLI$_PRESENT or CLI$_ NEGATED. / 


To determine whether a positional qualifier is used locally, call 
CLI$PRESENT immediately after a parameter value has been fetched 

by CLI$GET_VALUE. The most recent CLISGET_VALUE call to fetch 

a parameter defines the context for a qualifier search. Therefore, 
CLI$PRESENT tests whether a positional qualifier was specified after 
the parameter that was fetched by the most recent CLI$SGET_VALUE call. 
If the positional qualifier is used locally, CLISPRESENT returns either 
CLI$_LOCPRES or CLI$_LOCNEG. 





CONDITION 
VALUES 
RETURNED 
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CLI$_PRESENT Specified entity present in the command string. This 

status is returned for all entities except local qualifiers 

and positional qualifiers that are used locally. 
CLI$_NEGATED Specified qualifier present in negated form (with /NO) 

and used as a global qualifier. ( 
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CLISPRESENT 

CLI$_LOCPRES Specified qualifier present and used as a local 
qualifier. 

CLI$_LOCNEG Specified qualifier present in negated form (with /NO) 
and used as a local qualifier. 

CLI$_DEFAULTED Specified entity not present, but it is present by 
default. 

CLI$_ABSENT Specified entity not present, and it is not present by 
default. 
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Convert (CONV) Routines 


This chapter describes the Convert routines. These routines perform the 
functions of both the VMS RMS Convert and Convert/Reclaim Utilities. 





Introduction to Convert Routines 


The Convert Utility copies records from one or more files to an output file, 
changing the record format and file organization to that of the output file. 
You can invoke the functions of the Convert Utility from within a program 
by calling the following series of three routines, in this order: 


1 CONV$PASS_FILES 

2 CONV$PASS_OPTIONS 

3 CONV$CONVERT 

Note that the application program should declare referenced contants and 


return status symbols as external symbols; these symbols are resolved 
upon linking with utility shareable image. 


The Convert/Reclaim Utility reclaims empty buckets in Prolog 3 indexed 
files so that new records can be written in them. You can invoke the 
functions of the Convert/Reclaim Utility from within a program by calling 
the CONV$RECLAIM routine. 


These routines cannot be called from AST level. 





Using the Convert Routines: Examples 


Example 4~1 shows how to use the Convert routines in a FORTRAN 
program. 
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Example 4-1 Using the Convert Routines in a FORTRAN Program 


+ + + FF HF HF HF 


+ + FF He F 


+ + e 


1000 





This program calls the routines that perform the 
functions of the Convert Utility. It creates an 
indexed output file named CUSTDATA.DAT from the 

specifications in an FDL file named INDEXED.FDL. 
The program then loads CUSTDATA.DAT with records 
from the sequential file SEQ.DAT. No exception 

file is created. This program also returns all 

the CONVERT statistics. 


Program declarations 
IMPLICIT INTEGER*4 (A - 2Z) 


Set up parameter list: number of options, CREATE, 
NOSHARE, FAST LOAD, MERGE, APPEND, SORT, WORK _FILES, 
KEY=0, NOPAD, PAD CHARACTER, NOTRUNCATE, 

NOEXIT, NOFIXED CONTROL, FILL BUCKETS, NOREAD CHECK, 
NOWRITE CHECK, FDL, and NOEXCEPTION. 


INTEGER* 4 OPTIONS (19) 
1. “$1671.07 15070;15-240700,0,040,0,0,07.1,07 


Set up statistics list. Pass an array with the 
number of statistics that you want. There are four 
-~-~ number of files, number of records, exception 
records, and good records, in that order. 


INTEGER* 4 STATSBLK(5) /4,0,0,0,0/ 


Declare the file names. 


CHARACTER IN_FILE*7 /’SEQ.DAT’/, 
1 OUT_FILE*12 /’CUSTDATA.DAT’/, 
a FDL_FILE*11 /’ INDEXED.FDL’ / 


Call the routines in their required order. 


STATUS = CONVSPASS FILES (IN_FILE, OUT_FILE, FDL FILE) 
IF (.NOT. STATUS) CALL LIBSSTOP (%VAL(STATUS) ) 


STATUS = CONVSPASS OPTIONS (OPTIONS) ( 
IF (.NOT. STATUS) CALL LIBSSTOP (%SVAL(STATUS) ) 


STATUS = CONVSCONVERT (STATSBLK) 
IF (.NOT. STATUS) CALL LIBSSTOP (%VAL (STATUS) ) 


Display the statistics information. 


WRITE (6,1000) (STATSBLK (I) ,I=2,5) 
FORMAT (1X,’Number of files processed: ’,I5/, 


1 1X,’Number of records: ’,I5/, 

1 1X,’Number of exception records: ’,I15/, 
1 1X,’Number of valid records: ’,I15) 

END 





Example 4~—2 shows how to use the Convert routines in a MACRO 


program. 
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Example 4-2 Using the Convert Routines ina MACRO Program 





-TITLE CONVSTAT.MAR 


This module calls the routines that perform the functions 
of the Convert Utility. It creates an indexed output file 
named CUSTDATA.DAT from the specifications in an FDL file 
named INDEXED.FDL, and loads CUSTDATA.DAT with records from 
the sequential file SEQ.DAT. No exception file is created. 
+ This module also returns all the CONVERT statistics. 


’ 


; Declare the file names. 


™e Se Ne 


Ne Me Ne 


FILEIN: -ASCID /SEQ.DAT/ 
FILEOUT: -ASCID /CUSTDATA.DAT/ 


FDLFILE: -ASCID / INDEXED .FDL/ 


’ 


; Set up parameter list. 


. 
f 


PARAM LIST: -LONG 18 7;NUMBER OF LONGWORDS FOLLOWING 
- LONG 1 7; CREATE 
. LONG 0 7 NOSHARE 
- LONG 1 7FAST LOAD 
. LONG 0 7 MERGE 
. LONG 0 7 APPEND 
. LONG a 7; SORT 
- LONG 2 7WORK_FILES 
. LONG 0 ; KEY=0 
- LONG 0 7 NOPAD 
- LONG 0 7;PAD CHARACTER 
. LONG 0 ; NOTRUNCATE 
- LONG 0 7NOEXIT 
. LONG 0 ;NOFIXED CONTROL 
. LONG 0 ;FILL BUCKETS 
. LONG 0 ;NOREAD_CHECK 
. LONG 0 ;NOWRITE CHECK 
. LONG 1 7FDL 
. LONG 0 7 NOEXCEPTION 


, Have to use Formatted ASCII Output (FAO) conversion 
; Declare FAO info for statistics 


FAO DESC: . LONG 132 
. LONG FAO BUFFER 
FAO BUFFER: . BLKB 132 
FAO LEN: . BLKL 1 
OUTSTUFF: -ASCID #Number of files processed: !UL !/- 


Number of records: !UL !/- 
Number of exception records: !UL !/- 
Number of valid records: !UL !/# 





(continued on next page) 
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Example 4-2 (Cont.) Using the Convert Routines in a MACRO Program 





; Have to pass a longword to the CONVSCONVERT ROUTINE with the 
; mumber of statistics that we want. There are 4 -- number of 
; files, number of records, exception records, good records, 

; ain that order. 


STATSBLK: -LONG 4 ;The value 4 is the number of statistics 
;that we want. we pass this value to 
#the END_CONVERT routine. 


STATS: -BLKL 4 ;Where we place the statistics. This block 
;must follow the longword that tells how 
Many stats we want. 


TIMES: ~-BLKL 5 ;Where we place the timing info. 
; Declare the external routines. 
» EXTRN CONVSPASS_ FILES, CONVSPASS_OPTIONS, CONVSCONVERT, ~ 
LIBSPUT_OUTPUT, LIBSINIT_TIMER, LIBS$SYS_FAOL | 


-ENTRY CONV, *M<R2,R3,R4,R5,R6,R7> ;SAVE THOSE REGISTERS; 
; Perform operations. Push addresses on arg stack, call routines. 


PUSHAL TIMES 
CALLS #1,G*LIBSINIT_ TIMER ;Start the timer 


PUSHAL FDLFILE 

PUSHAL FILEOUT 

PUSHAL FILEIN 7Push filenames on arg stack 
CALLS #3,G*CONVSPASS FILES ;Pass filenames 

BLBC RO,10$ 


PUSHAL PARAM LIST 7Push parameter list 
CALLS #1,G*CONVSPASS_ OPTIONS #Make the second call 
BLBC RO,10$ 


PUSHAL STATSBLK ;Push address of the number of 
; Statistics 
CALLS #1,G*CONVSCONVERT ;Perform conversion 


BLBC RO, 10$ 


>; Now need an FAO routine to format the counts 


$FAOL_S CTRSTR=OUTSTUFF, OUTLEN=FAO_LEN, OUTBUF=FAO_DESC, - 
PRMLST=STATS 
BLBC RO,10$ 


PUSHAL FAO _DESC #Push output buffer on stack 
CALLS #1,G*LIBSPUT_OUTPUT ;Send the output buffer to 
; SYSSOUTPUT 


BLBC RO,10$ 





(continued on next page) 
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; Display times 
PUSHAL TIMES 
CALLS #1,G*LIBSSHOW_TIMER 
BLBC RO,10$ 
MOVL #SS$_ NORMAL, RO 


108: RET 


- BND CONV 


Example 4—3 shows how to use the CONV$RECLAIM routine in a 
FORTRAN program. 


Example 4-3 Using the CONV$RECLAIM Routine in a FORTRAN 
Program 





This program calls the routine that performs the 
function of the Convert/Reclaim Utility. It 
reclaims empty buckets from an indexed file named 
PROL3.DAT. It also returns all the CONVERT/RECLAIM 
statistics. 

Program declarations 


+ + F F HF 


IMPLICIT INTEGER*4 (A - 2) 


ba 


Set up a statistics block. There are four --- data 
buckets scanned, data buckets reclaimed, index 
* buckets reclaimed, total buckets reclaimed. 


INTEGER* 4 OUTSTATS(5) /4,0,0,0,0/ 


* 


* Declare the input file. 
CHARACTER IN_FILE*9 /’PROL3.DAT!’ / 
* Call the routine. 


STATUS = CONVSRECLAIM (IN_FILE, OUTSTATS) 
IF (.NOT. STATUS) CALL LIBSSTOP (%VAL(STATUS) ) 


* Display the statistics. 


WRITE (6,1000) (OUTSTATS (I), I=2,5) 
1000 FORMAT (1X,’Number of data buckets scanned: ’,I15/, 


1 1X,’Number of data buckets reclaimed: ’',I15/, 
1 1X,’Number of index buckets reclaimed: ',I5/, 
i 1X,’Total buckets reclaimed: ’,I15) 

END 





Example 4—4 shows how to use the CONV$RECLAIM routine in a MACRO 
program. 
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Example 4—4 Using the CONV$RECLAIM Routine in a MACRO Program 





-TITLE CONVREC.MAR 


=e 


This module calls the routine that performs the 
function of the CONVERT/RECLAIM Utility. It reclaims 
empty buckets from an indexed file named PROL3.DAT. 


This module also returns all of the CONVERT/RECLAIM 
statistics. 


Ne Ne Ne Ne Ne Ne Ne 


Ne 


Declare the file name. 


ee 


FILEIN: -ASCID /PROL3.DAT/ 


; Declare statistics blocks 


OUTSTATS: .- LONG 4 
- BLKL 4 
; Declare FAO info for statistics 


. 
f 


FAO DESC: - LONG 132 
. LONG FAO_BUFFER 
FAO BUFFER: - BLKB 132 
FAO LEN: “BLKL:. <1 
OUTSTUFF: -ASCID #Data buckets scanned: !UL !/- 


Data buckets reclaimed: !UL !/- 
Index buckets reclaimed: !UL !/- 
Total buckets reclaimed: !UL !/# 


; Looking for four statistics back from the end call. 
; Use FAO conversion. 


; Declare the external routines. 
-EXTRN CONVSRECLAIM, LIBSPUT_OUTPUT 
-ENTRY CONV, *M<> 
; Perform operations. Push addresses on arg stack, call 
; routines. 
PUSHAL OUTSTATS 
PUSHAL FILEIN ;PUSH FILENAME ON ARG STACK 


CALLS #2, G*CONVSRECLAIM 7PASS FILENAME 
BLBC RO,10$ 





(continued on next page) 
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Example 4—4 (Cont.) Using the CONV$RECLAIM Routine in a MACRO Program 


Now need an FAO routine to format the counts. 


we Ne Ne Ne 


SFAOL_S CTRSTR=OUTSTUFF, OUTLEN=FAO_LEN, OUTBUF=FAO_DESC, - 
PRMLST=OUTSTATS+4 


BLBC RO,10$ 
; 
PUSHAL FAO_DESC ;PUSH OUTPUT BUFFER ON STACK 
CALLS #1,G*LIBSPUT_OUTPUT ;SEND THE OUTPUT BUFFER TO 
; SYSSOUTPUT 
BLBC RO,10$ 
MOVL #SS$_ NORMAL, RO 
10S: RET 
.END CONV 





Convert Routines 


The following pages describe the individual Convert routines. 
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CONVSCONVERT Initiate Conversion 


The CONV$CONVERT routine uses the Convert Utility to perform the actual 
conversion begun with CONV$PASS_ FILES and CONV$PASS_OPTIONS. 
Optionally, the routine can return statistics about the conversion. 








FORMAT CONV$CONVERT [siatus_block_address] [, flags] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _ status_block_address 
VMS usage: vector_longword_unsigned 
type: longword (unsigned) \ 
access: write only 
mechanism: by reference 
The conversion statistics. The status_block_address argument is the 
address of a variable-length array of longwords that receives statistics 
about the conversion. The format of the array is as follows: 


number of statistics 

number of files 

number of records 

number of exception records | 
number of valid records 


flags 

VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Flags (or masks) that control how the fdl_filespec argument is interpreted 
and how errors are signalled. The flags argument is the address of a 
longword containing control flags (or a mask). If you omit the flags 
argument or specify it as zero, no flags are set. The flags and their 
meanings are described in the following table. 
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Flag 
CONV$V_FDL_STRING 


CONV$V_SIGNAL 
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Function 


Interprets the fdl_filespec argument supplied in the call 
to CONV$PASS_FILES as an FDL specification in string 
form. By default, this argument is interpreted as a file 
name of an FDL file. 


Signals any error. By default, the status code is returned 
to the calling image. 


This argument is optional. By default, an error status is returned rather 


than signalled. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL 
CONV$_BADBLK 
CONV$_BADLOGIC 
CONV$_BADSORT 
CONV$_CLOSEIN 
CONV$_CLOSEOUT 
CONV$_CONFQUAL 
CONV$_CREA_ERR 
CONV$_CREATEDSTM 
CONV$_DELPRI 
CONV$_DUP 
CONV$_EXTN_ERR 
CONV$_FATALEXC 
CONV$_FILLIM 
CONV$_IDX_LIM 
CONV$_ILL_KEY 
CONV$_ILL_VALUE 
CONV$_INP_FILES 
CONV$_INSVIRMEM 
CONV$_KEY 
CONV$_LOADIDX 
CONV$_NARG 
CONV$_NOKEY 
CONV$_NOTIDX 
CONV$_NOTSEQ 
CONV$_NOWILD 
CONV$_OPENEXC 
CONV$_OPENIN 
CONV$_OPENOUT 
CONV$_ORDER 


Normal successful completion. 

Invalid option block. 

Internal logic error detected. 

Error trying to sort input file. 

Error closing file specification as input. 
Error closing file specification as output. 
Conflicting qualifiers. 

Error creating output file. 

File specification has been created in stream format. 
Cannot delete primary key. 

Duplicate key encountered. 

Unable to extend output file. 

Fatal exception encountered. 

Exceeded open file limit. 

Exceeded maximum index level. 

Illegal key or value out of range. 

Illegal parameter value. 

Too many input files. 

Insufficient virtual memory. 

Invalid record key. 

Error loading secondary index n. 

Wrong number of arguments. 

No such key. 

File is not an indexed file. 

Output file is not a sequential file. 

No wildcard permitted. 

Error opening exception file specification. 
Error opening file specification as input. 
Error opening file specification as output. 
Routine called out of order. 
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CONV$_PAD 
CONV$_PLV 
CONV$_PROERR 
CONV$_PROL_WRT 
CONV$_READERR 
CONV$_REX 
CONV$_RMS 
CONV$_RSK 
CONV$_RSZ 
CONV$_RTL 
CONV$_RTS 
CONV$_SEQ 
CONV$_UDF_BKS 
CONV$_UDF_BLK 
CONV$_VALERR 
CONV$_VFC 
CONV$_WRITEERR 
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PAD option ignored; output record format not fixed. 
Unsupported prolog version. 

Error reading prolog. 

Prolog write error. 

Error reading file specification. 

Record already exists. 

Record caused RMS severe error. 

Record shorter than primary key. 

Record does not fit in block/bucket. 

Record longer than maximum record length. 
Record too short for fixed record format file. 
Record not in order. 

Cannot convert UDF records into spanned file. 
Cannot fit UDF records into single block bucket. 
Specified value is out of legal range. 

Record too short to fill fixed part of VFC record. 
Error writing file specification. 
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CONV$PASS FILES Specify Conversion Files 


The CONV$PASS_FILES routine specifies a file to be converted using the 








CONVS$CONVERT routine. 
FORMAT CONV$PASS FILES input_filespec ,output_filespec 
,[fdl_filespec] 
,[exception_filespec] 
[flags] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _ input_filespec 
VMS usage: char_string 
type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 
The name of the file to be converted. The input_filespec argument is 
the address of a string descriptor pointing to the name of the file to be 
converted. 


output_filespec 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 

The name of the file that receives the records from the input file. The 
output_filespec argument is the address of a string descriptor pointing to 
the name of the file that receives the records from the input file. 


fdl_filespec 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 

The name of the FDL file that defines the output file. The fdl_filespec 
argument is the address of a string descriptor pointing to the name of the 
FDL file. 
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exception_filespec 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 

The name of the file that receives copies of records that cannot be written 
to the output file. The exception_filespec argument is the address of a 


string descriptor pointing to this name. 


flags 

VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Flags (or masks) that control how the fdl_filespec argument is interpreted 
and how errors are signalled. The flags argument is the address of a 
longword containing the control flags (or mask). If you omit this argument 
or specify it as zero, no flags are set. If you specify a flag, it remains in 
effect until you explicitly reset it in a subsequent call to a Convert routine. 


The flags and their meanings are described in the following table. 


Flag Function 
CONV$V_FDL_STRING Interprets the fdl_filespec argument as an FDL / 


specification in string form. By default, this argument 
is interpreted as a file name of an FDL file. 


CONV$V_SIGNAL Signals any error. By default, the status code is returned 
to the calling image. 


This argument is optional. By default, an error status is returned rather 
than signalled. 





DESCRIPTION 
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The CONV$PASS_FILES routine specifies a file to be converted using the \ 
CONV$CONVERT routine. A single call to CONV$PASS_FILES allows 

you to specify an input file, an output file, an FDL file, and an exception 

file. If you have multiple input files, you must call CONV$PASS_FILES 

once for each file. You need to specify only the input_filespec argument 

for the additional files, as follows: 


status = CONVSPASS FILES (input_filespec) 


The additional calls must immediately follow the original call that 
specified the output file specification. You may specify as many as 9 
additional files for a maximum total of 10. 


Wildcard characters are not allowed in the file specifications passed to the 
Convert routines. 
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CONDITION . 
SS$_NORMAL Normal successful completion. 

VALUES nS 

RETURNED CONV$_INP_FILES Too many input files. 
CONV$_INSVIRMEM Insufficient virtual memory. 
CONV$_NARG Wrong number of arguments. 
CONV$_ORDER Routine called out of order. 
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CONV$PASS OPTIONS Specify Processing Options 


The CONV$PASS_OPTIONS routine specifies which qualifiers are to be used 
by the Convert Utility (CONVERT). 





FORMAT 


CONV$PASS OPTIONS | [/parameter_list_address] 
[, flags] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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parameter_list_address 

VMS usage: vector_longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Parameter list specifying information about the CONVERT qualifiers. The 
parameter_list_address argument is the address of a variable-length 
array of longwords. The first longword in the array is the number of 
parameters in the array. Each subsequent longword in the array (from the 
second one on) is associated with one of the CONVERT qualifiers. These 
functions are described in the VMS Convert and Convert /Reclaim Utility 
Manual. 


To set one of the CONVERT qualifiers, you place a J in the longword 
associated with that qualifier. If you do not want to set one of the 
qualifiers (which has the same effect as using the negative form of 
the qualifier on the CONVERT command), you place a 0 in the correct 
longword. 


If you do not specify parameter_list_address, then the following default 
values apply. You can also take all default values by passing the address of 
a longword that contains 0, which means a parameter list of 0 longwords. 


If you have specified all the values you want set, you may want to take the 
default values for all subsequent qualifiers in the list. You may omit the 
subsequent ones if you give the array length in the first longword. This is 
why the first longword contains a count of the qualifiers. 


The qualifiers must appear in the following order. 


Qualifier 


CREATE 
SHARE 
FAST_LOAD 
MERGE 
APPEND 

SORT 
WORK_FILES 
KEY 

PAD 

Pad character 
TRUNCATE 
EXIT 
FIXED_CONTROL 
FILL_BUCKETS 
READ_CHECK 
WRITE_CHECK 
FDL 
EXCEPTION 
PROLOG 


Default Value (in 
Longwords) 


oo ooo0oe0o0ncneoaoeoao ont Ooo H 0 = 


No default 


Convert (CONV) Routines 


CONV$PASS_OPTIONS 


Default CONVERT Value 


/CREATE 

/NOSHARE 
/FAST_LOAD 
/NOMERGE 
/NOAPPEND 

/SORT 
/WORK_FILES=2 
/KEY=0 

/NOPAD 

Pad character=0 
/NOTRUNCATE 
/NOEXIT 
/NOFIXED_CONTROL 
/NOFILL_BUCKETS 
/NOREAD_CHECK 
/NOWRITE_CHECK 
/NOFDL 
/NOEXCEPTION 
System or process default 


If you want to use the default null character for the PAD qualifier, you 
should specify 0 in the pad character longword. You can also specify the 
default null character by omitting the pad character longword. However, 
in this case, you must also take the default values for all subsequent 
qualifiers. To specify a pad character other than 0, place the ASCII value 
of the character you want to use in the PAD qualifier longword. 


If you specify /EXIT and the utility encounters an exception record, then 
CONVERT returns with a fatal exception status. 


If you specify an FDL file specification in the CONV$PASS_FILES routine, 
you must place a 1 in the FDL longword. If you also specify an exceptions 
file specification in the CONV$PASS_FILES routine, you must place a 1 
in the EXCEPTION longword. You may specify either, both, or neither of 
these files, but the values in the CONV$PASS_FILES call must match the 
values in the parameter list. If they do not, the routine returns an error. 


If you specify the PROLOG longword, note that this overrides the KEY 
PROLOG attribute supplied by the FDL file. You must supply one of three 
values for the PROLOG longword if you use it. The three values are 0, 

2, and 3. The value 0 means that you want to use the system or process 
prolog type. The value 2 means that you want to create a Prolog 1 or 2 
file in all instances, even when circumstances would allow you to create 

a Prolog 3 file. The value 3 means that you want to create a Prolog 3 file 
and, if circumstances do not allow you to, you want the conversion to fail. 
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flags 
VMS usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 

by reference 


Flags (or masks) that control how the fdl_filespec argument is interpreted 
and how errors are signalled. The flags argument is the address of 

a longword containing the control flags (or a mask). If you omit this 
argument or specify it as zero, no flags are set. If you specify a flag, it 
remains in effect until you explicitly reset it in a subsequent call to a 
Convert routine. 


The flags and their meanings are described in the following table. 


Flag 


CONV$V_FDL_STRING 


FDL$V_SIGNAL 


Function 


Interprets the fdl_filespec argument supplied in the call 
to CONV$PASS_FILES as an FDL specification in string 
form. By default, this argument is interpreted as a file 
name of an FDL file. 


Signals any error. By default, the status code is returned 
to the calling image. 


This argument is optional. By default, an error status is returned rather 
than signalled. 5 





DESCRIPTION The following example shows how to use the option array to reflect the 
CONVERT command: 


$ CONVERT/FAST LOAD/SORT/WORK_FILES=6/EXIT 


A: 


— 
mM 


- OO 0 00 = 007+ 0 — 
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Specifies that 12 longwords follow 
Specifies the /CREATE option 
Specifies the /NOSHARE option ] 
Specifies the /FASTLOAD option 
Specifies the /NOMERGE option 
Specifies the /NOAPPEND option 
Specifies the /SORT option 
Specifies the (WWORKFILES=6 option 
Specifies the /KEY=0 option 
Specifies the /NOPAD option 
Specifies the null pad character 
Specifies the /(NOTRUNCATE option 
Specifies the /EXIT option 


Convert (CONV) Routines 
CONV$PASS_OPTIONS 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL 
CONV$_BADBLK 
CONV$_CONFQUAL 
CONV$_INSVIRMEM 
CONV$_NARG 
CONV$_OPENEXC 
CONV$_ORDER 


Normal successful completion. 
Invalid option block. 

Conflicting qualifiers. 

insufficient virtual memory. 

Wrong number of arguments. 

Error opening exception file filespec. 
Routine called out of order. 
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CONV$RECLAIM Invoke Convert/Reclaim Utility 


The CONV$RECLAIM routine invokes the functions of the Convert/Reclaim 








Utility. 
FORMAT CONV$RECLAIM input_filespec [, statistics_blk] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _ input_filespec 
VMS usage: char_string 
type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 
Name of the Prolog 3 indexed file to be reclaimed. The input_filespec 
argument is the address of a string descriptor pointing to the name of the 
Prolog 3 indexed file. 


statistics_blk 

VMS usage: vector_longword_unsigned 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Bucket reclamation statistics. The statistics_blk argument is the 
address of a variable-length array of longwords to receive statistics on 
the bucket reclamation. You can choose which statistics you want returned 
by specifying a number in the first element of the array. This number 
determines how many of the four possible statistics the routine returns. 
Depending on the number chosen, the routine returns the statistics in the 
statistics array in the order specified by the following format: 


A: Number of statistics 
Data buckets scanned 
Data buckets reclaimed 
Index buckets reclaimed 
Total buckets reclaimed 
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Convert (CONV) Routines 
CONV$RECLAIM 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL 
CONV$_BADLOGIC 
CONV$_INSVIRMEM 
CONV$_INVBKT 
CONV$_NOTIDX 
CONV$_OPENIN 
CONV$_PLV 
CONV$_PROERR 
CONV$_PROL_WRT 
CONV$_READERR 
CONV$_NOWILD 
CONV$_WRITEERR 


Normal successful completion. 
Internal logic error detected. 
Insufficient virtual memory. 
Invalid bucket at VBN n. 

File is not an index file. 

Error opening filespec as input. 
Unsupported prolog version. 
Error reading prolog. 

Prolog write error. 

Error reading filespec. 

No wildcard permitted. 

Error writing output file. 
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5 Data Compression/Expansion (DCX) Routines 


The set of routines described in this chapter comprises the VMS Data 
Compression/Expansion (DCX) facility. There is no DCL-level interface to 
this facility nor is there a DCX Utility. 


5.1 introduction to DCX Routines 


Using the DCX routines described in this chapter, you can decrease the 
size of text, binary data, images, and any other type of data. Compressed 
data uses less space, but there is a trade-off in terms of access time to the 
data. Compressed data must first be expanded to its original state before 
it is usable. Thus, infrequently accessed data makes a good candidate for 
data compression. 


The DCX facility provides routines that analyze and compress data records 
and expand the compressed records to their original state. In this process, 
no information is lost. A data record that has been compressed and then 
expanded is in the same state as it was before it was compressed. 


Most collections of data can be reduced in size by DCX. However, there 
is no guarantee that the size of an individual data record will always be 
smaller after compression; in fact, some may grow larger. 


The DCX facility allows for the independent analysis, compression, and 
expansion of more than one stream of data records at the same time. 
This capability is provided by means of a “context variable,” which is an 
argument in each DCX routine. Most applications have no need for this 
capability; for these applications, there is a single context variable. 


The procedure for using the DCX routines to perform data compression 
and expansion consists of three major steps. The list under each of the 
following steps shows the DCX routines used to perform that step: 


1 Analyze some or all of the data records in the data file to produce a 
mapping function (or map). 


DCX$ANALYZE_INIT 
DCX$ANALYZE_DATA 
DCX$MAKE_MAP 
DCX$ANALYZE_DONE 


2 Compress the data records in the file on the basis of the mapping 
function. 


DCX$COMPRESS_INIT 
DCX$COMPRESS_DATA 
DCX$COMPRESS_DONE 
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Data Compression/Expansion (DCX) Routines 
5.1 Introduction to DCX Routines 


3 Expand the compressed data records on the basis of the mapping 
function. 


DCX$EXPAND_INIT 
DCX$EXPAND_DATA 
DCX$EXPAND_DONE 


Some of the DCX routines make calls to various Run-Time Library (RTL) 
routines, LIB$GET_VM, for example. If any of these RTL routines should 
fail, a return status code indicating the cause of the failure is returned. In 
such a case, you must refer to the documentation of the appropriate RTL 
routine to determine the cause of the failure. The status codes documented 
in this chapter are primarily DCX status codes. 


Note also that the application program should declare referenced constants 
and return status symbols as external symbols; these symbols are resolved 
upon linking with the utility shareable image. 


5.2 Using the DCX Routines: Examples 
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Examples 5-1 and 5-2 show how to use the DCX routines in VAX 
FORTRAN programs. 


Example 5-1 Compressing a File in a VAX FORTRAN Program 


PROGRAM COMPRESS FILES 
! COMPRESSION OF FILES 


! status variable 
INTEGER STATUS, 


2 IOSTAT, 
2 IO_OK, 
2 STATUS _OK 


PARAMETER (IO_OK = 0) 
PARAMETER (STATUS OK = 1) 
INCLUDE ’ (SFORDEF) ’ 
EXTERNAL DCX$_AGAIN 


! context variable 

INTEGER CONTEXT 

! compression/expansion function 
INTEGER MAP, 

2 MAP LEN 


! normal file name, length, and logical unit number 
CHARACTER*256 NORM NAME 

INTEGER*2 NORM LEN 

INTEGER NORM_LUN 

! compressed file name, length, and logical unit number 
CHARACTER*256 COMP_NAME 

INTEGER*2 COMP_LEN 

INTEGER COMP LUN 


(continued on next page) 
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Example 5—1 (Cont.) Compressing a File in a VAX FORTRAN Program 





! Logical end-of-file 

LOGICAL EOF 

! record buffers; 32764 is maximum record size 
CHARACTER* 32764 RECORD, 


2 RECORD2 
INTEGER RECORD LEN, 
2 RECORD2_LEN 


! user routine 
INTEGER GET MAP, 
2 WRITE MAP 


! Library procedures 
INTEGER DCXSANALYZE_ INIT, 
DCXSANALYZE_DONE, 
DCXSCOMPRESS_INIT, 
DCX$COMPRESS DATA, 
DCX$COMPRESS_DONE, 
LIBSGET_INPUT, 
LIBSGET_LUN, 
LIBSFREE_VM 


MNNM NN N 


! get name of file to be compressed and open it 
STATUS = LIBSGET_INPUT (NORM_NAME, 

2 ‘File to compress: ', 

2 NORM_LEN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
STATUS = LIBSGET_LUN (NORM_LUN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
OPEN (UNIT = NORM_LUN, 


2 FILE = NORM NAME (1:NORM_LEN), 
2 CARRIAGECONTROL = ‘NONE’, 
2 STATUS = ‘OLD’) 

KKKKKKEKKKEKE 


KKEKKKKKKKKK 


i] 
! ANALYZE DATA 
{ 
} 


! initialize work area 

STATUS = DCXSANALYZE_INIT (CONTEXT) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (SVAL(STATUS) ) 
! get compression/expansion function (map) 
STATUS = GET MAP (NORM LUN, 


2 CONTEXT, 
2 MAP, 
2 MAP LEN) 


DO WHILE (STATUS .EQ. LOC (DCX$_AGAIN) ) 
! go back to beginning of file 
REWIND (UNIT = NORM_LUN) 

! try map again 
STATUS = GET MAP (NORM LUN, 

2 CONTEXT, 

2 MAP, 

2 MAP _LEN) 

END DO : 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS) ) 

! clean up work area 

STATUS = DCXSANALYZE_DONE (CONTEXT) 





(continued on next page) 
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Example 5—1 (Cont.) Compressing a File in a VAX FORTRAN Program 


IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 


2k OR do kk 
COMPRESS DATA 


! 

! 

! KKKKKKKKKKKEK 

! go back to beginning of file to be compressed 
REWIND (UNIT = NORM_LUN) 

! open file to hold compressed records 

STATUS = LIBSGET_LUN (COMP_LUN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
STATUS = LIBSGET_ INPUT (COMP_NAME, 

2 ‘File for compressed records: ’, 
2 COMP _LEN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%$VAL(STATUS) ) 
OPEN (UNIT = COMP_LUN, 


2 FILE = COMP NAME(1:COMP LEN), 
2 STATUS = ‘NEW’, 
2 FORM = ’UNFORMATTED’ ) 


! initialize work area 

STATUS = DCXSCOMPRESS_INIT (CONTEXT, 

2 MAP ) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 

! write compression/expansion function to new file 
CALL WRITE MAP (COMP LUN, 


2 %VAL (MAP), 
2 MAP LEN) 


! read record from file to be compressed \ 
KOF = .FALSE. 
READ (UNIT = NORM _LUN, 


2 FMT = ’ (Q,A)’', 
2 IOSTAT = IOSTAT) RECORD _LEN, 
2 RECORD (1:RECORD_LEN) 


IF (IOSTAT .NE. IO OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIBS$SIGNAL (%VAL(STATUS) ) 


ELSE 
EOF = .TRUE. ( 
STATUS = STATUS_OK 
END IF 
END IF 





(continued on next page) 
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Example 5—1 (Cont.) Compressing a File in a VAX FORTRAN Program 





DO WHILE (.NOT. EOF) 
! compress the record 
STATUS = DCXSCOMPRESS DATA (CONTEXT, 
2 RECORD (1:RECORD_ LEN), 
2 RECORD2, 
2 RECORD2_LEN) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
! write compressed record to new file 
WRITE (UNIT = COMP_LUN) RECORD2_ LEN 
WRITE (UNIT = COMP LUN) RECORD2 (1:RECORD2_ LEN) 
! read from file to be compressed 
READ (UNIT = NORM LUN, 
FMT = ‘ (Q,A)’, 
IOSTAT = IOSTAT) RECORD_LEN, 
RECORD (1:RECORD_ LEN) 
IF (IOSTAT .NE. IO _OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FORS$_ENDDURREA) THEN 
CALL LIBSSIGNAL (%VAL(STATUS) ) 


NN NM 


ELSE 
'EOF = .TRUE. 
STATUS = STATUS _OK 
END IF 
END IF 
END DO 


! close files and clean up work area 

CLOSE (NORM_LUN) 

CLOSE (COMP_LUN) 

STATUS = LIBSFREE_VM (MAP LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
STATUS = DCXSCOMPRESS DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 


END 

INTEGER FUNCTION GET MAP (LUN, ! passed 
CONTEXT, !. passed 
MAP, ! returned 
MAP _LEN) ! returned 


Analyzes records in file opened on logical 
unit LUN and then attempts to create a 
compression/expansion function using 
DCX$MAKE MAP. 


te eee MND 


! dummy arguments 

! context variable 

INTEGER CONTEXT 

! logical unit number 

INTEGER LUN 

! compression/expansion function 
INTEGER MAP, 

2 MAP LEN 


(continued on next page) 
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Example 5—1 (Cont.) Compressing a File in a VAX FORTRAN Program 





! status variable 
INTEGER STATUS, 


2 IOSTAT, 
2 IO_OK, 
2 STATUS OK 


PARAMETER (IO OK = 0) 
PARAMETER (STATUS OK = 1) 
INCLUDE ’ ($FORDEF) ' 


! Logical end-of-file 

LOGICAL EOF 

! record buffer; 32764 is the maximum record size 
CHARACTER*32764 RECORD 

INTEGER RECORD LEN 


! library procedures 
INTEGER DCXSANALYZE_DATA, 
2 DCX$MAKE_MAP 


! analyze records 
EOF = .FALSE. 
READ (UNIT = LUN, 
2 FMT = ' (Q,A)', 
2 TOSTAT = IOSTAT) RECORD_LEN, RECORD 
IF (IOSTAT .NE. IO OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FORS$_ENDDURREA) THEN 
CALL LIBSSIGNAL (%VAL(STATUS) ) 
ELSE 
EOF = .TRUE. 
STATUS = STATUS _OK 
END IF 
END IF 


DO WHILE (.NOT. EOF) 

STATUS = DCXSANALYZE DATA (CONTEXT, 

2 RECORD (1:RECORD_LEN) ) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
READ (UNIT = LUN, 

2 FMT = ’(Q,A)’, 

2 IOSTAT = IOSTAT) RECORD _LEN, RECORD 
IF (IOSTAT .NE. IO OK) THEN 

CALL ERRSNS (,,,,STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIBSSIGNAL (%VAL(STATUS) ) 
ELSE 
EOF = .TRUE. 

STATUS = STATUS OK 


END IF 
END IF 
END DO 
STATUS = DCX$MAKE MAP (CONTEXT, 
2 MAP, 
2 MAP_LEN) 


GET_MAP = STATUS 
END 
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Example 5—1 (Cont.) Compressing a File in a VAX FORTRAN Program 





SUBROUTINE WRITE MAP (LUN, ! passed 
2 MAP, ! passed 
2 MAP LEN) ! passed 


IMPLICIT INTEGER (A-Z) 
! write compression/expansion function 
! to file of compressed data 


! dummy arguments 


INTEGER LUN, ! logical unit of file 
2 MAP_LEN ! length of function 
BYTE MAP (MAP LEN) ! compression/expansion function 


! write map length 

WRITE (UNIT = LUN) MAP _ LEN 
! write map 

WRITE (UNIT = LUN) MAP 


END 





Example 5-2 Expanding a Compressed File in a VAX FORTRAN 
Program 





PROGRAM EXPAND FILES 
IMPLICIT INTEGER (AZ) 
! EXPANSION OF COMPRESSED FILES 


! file names, lengths, and logical unit numbers 
CHARACTER*256 OLD FILE, 

2 NEW_FILE 

INTEGER*2 OLD LEN, 

2 NEW_LEN 

INTEGER OLD LUN, 

2 NEW_LUN 


! length of compression/expansion function 
INTEGER MAP, 
2 MAP LEN 


! user routine 
EXTERNAL EXPAND DATA 


! library procedures 
INTEGER LIBSGET_LUN, 

2 LIBSGET_INPUT, 
Z LIBSGET_VM, 

2 LIBSFREE_VM 





(continued on next page) 
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Example 5-2 (Cont.) Expanding a Compressed File in a VAX FORTRAN 
Program 





! open file to expand 

STATUS = LIBSGET_LUN (OLD LUN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
STATUS = LIBSGET_INPUT (OLD FILE, 

2 ‘File to expand: ', 

2 OLD_LEN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
OPEN (UNIT = OLD LUN, 


2 STATUS = ’OLD’, 
2 FILE = OLD FILE(1:OLD_LEN), 
2 FORM = ‘UNFORMATTED’ ) 


! open file to hold expanded data 

STATUS = LIBSGET_LUN (NEW_LUN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 

STATUS = LIBSGET_INPUT (NEW _FILE, 

2 ‘Pile to hold expanded data: ’, 
2 NEW_LEN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 

OPEN (UNIT = NEW_LUN, 


2 STATUS = ‘’NEW’, 
2 CARRIAGECONTROL = ‘LIST’, 
2 FILE = NEW_FILE(1:NEW_LEN) ) 


! expand file 

! get length of compression/expansion function 

READ (UNIT = OLD _LUN) MAP LEN ; 
STATUS = LIBSGET_VM (MAP_LEN, \ 
2 MAP) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 

! expand records 

CALL EXPAND DATA (%VAL (MAP), 


2 MAP_LEN, ! length of function 
2 OLD_LUN, ! compressed data file 
2 NEW_LUN) ! expanded data file 


! delete virtual memory used for function 
STATUS = LIBSFREE_VM (MAP_LEN, 


2 MAP) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) ( 
END 

SUBROUTINE EXPAND DATA (MAP, ! passed 

2 MAP LEN, ! passed 

2 OLD_LUN, ! passed 

2 NEW_LUN) ! passed 

! 


expand data program 


! dummy arguments 

INTEGER MAP_LEN, ! length of expansion function 

2 OLD_LUN, ! logical unit of compressed file 
2 NEW_LUN ! logical unit of expanded file 
BYTE MAP(MAP LEN) ! array containing the function 
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Example 5-2 (Cont.) Expanding a Compressed File in a VAX FORTRAN 
Program 





! status variables 
INTEGER STATUS, 


2 IOSTAT, 
2 IO OK, 
2 STATUS OK 


PARAMETER (IO OK = 0) 
PARAMETER (STATUS OK = 1) 
INCLUDE ‘ (SFORDEF) ’ 


! context variable 
INTEGER CONTEXT 


! logical end_of file 
LOGICAL EOF 

! record buffers 
CHARACTER*32764 RECORD, 


2 RECORD2 
INTEGER RECORD LEN, 
2 RECORD2_LEN 


! library procedures 
INTEGER DCXSEXPAND_INIT, 
2 DCXS$EXPAND_DATA, 
2 DCXSEXPAND DONE 


! read data compression/expansion function 
READ (UNIT = OLD LUN) MAP 
! initialize work area 
STATUS = DCXSEXPAND_INIT (CONTEXT, 
2 SLOC (MAP (1) ) ) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
! expand records 
KOF = .FALSE. 
! read length of compressed record 
READ (UNIT = OLD LUN, 
Z IOSTAT = IOSTAT) RECORD_LEN 
IF (IOSTAT .NE. IO OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIBSSIGNAL (%VAL(STATUS) ) 
ELSE 
KOF = .TRUE. 
STATUS = STATUS _OK 
END IF 
END IF 
DO WHILE (.NOT. EOF) 
! read compressed record 
READ (UNIT = OLD LUN) RECORD (1:RECORD_LEN) 
! expand record 
STATUS = DCXSEXPAND DATA (CONTEXT, 
2 RECORD (1:RECORD_LEN), 
2 RECORD2, 
2 RECORD2_ LEN) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
! write expanded record to new file 
WRITE (UNIT = NEW_LUN, 
2 FMT = ’ (A)’) RECORD2 (1:RECORD2_ LEN) 
! read length of compressed record 





(continued on next page) 
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Example 5-2 (Cont.) Expanding a Compressed File in a VAX FORTRAN 
Program 


READ (UNIT = OLD LUN, 
2 IOSTAT = IOSTAT) RECORD_LEN 


IF (IOSTAT .NE. IO OK) THEN 


CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FOR$ _ENDDURREA) THEN 


CALL LIBSSIGNAL (%VAL(STATUS) ) 
ELSE 
EOF = .TRUE. 
STATUS = STATUS OK 
END IF 
END IF 


END DO 
! clean up work area 
STATUS = DCXSEXPAND_ DONE (CONTEXT) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 


END 





5.3 DCX Routines 


The following pages describe the individual DCX routines. 
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DCX$ANALYZE DATA Perform Statistical Analysis 


on a Data Record 


The DCX$ANALYZE_DATA routine performs statistical analysis on a data 
record. 


The results of the analysis are accumulated internally in the context area and 
are used by the DCX$MAKE_MAP routine to compute the mapping function. 





FORMAT 


DCX$ANALYZE DATA context ,record 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Value identifying the data stream that DCX$ANALYZE_DATA analyzes. 
The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT initializes this value; you should not modify it. You 
can define multiple context arguments to identify multiple data streams 
that are processed simultaneously. 


record 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Record to be analyzed. DCX$ANALYZE_DATA reads the record 
argument, which is the address of a descriptor for the record string. 
The maximum length of the record string is 65,535 characters. 





DESCRIPTION 


The DCX$ANALYZE_DATA routine performs statistical analysis on a 
single data record. This routine is called once for each data record to be 
analyzed. 
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During analysis, the data compression facility gathers information that 
DCX$MAKE_MAP uses to create the compression/expansion function 

for the file. After the data records have been analyzed, you call the 
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code 
from DCX$MAKE_MAP, you must again analyze the same data records (in 
the same order) using DCX$ANALYZE_DATA and then call DCX$MAKE_ 
MAP again. On the second iteration, DCX$MAKE_MAP returns the 
DCX$_NORMAL status code, and the data analysis is complete. 





CONDITION Basta ceute 
VALUES DCX$_INVCTX Error. The context variable is invalid, or the context 
area is invalid or corrupted. This may be caused by 
RETURNED a failure to call the appropriate routine to initialize the 
context variable or by an application program error. 
DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by 
LIB$ANALYZE_SDESC_R2. 
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DCX$ANALYZE DONE Specify Analysis Completed 


The DCX$ANALYZE_DONE routine deletes the context area and sets the 
context variable to zero, thus undoing the work of the DCX$ANALYZE_INIT 
routine. 


You call DOX$ANALYZE_DONE after data records have been analyzed and 
the DCX$MAKE_MAP routine has created the map. 














FORMAT DCX$ANALYZE DONE context 
RETURNS VMS usage: cond_value 
type: longword 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENT context 
VMS usage: context 
type: longword 
access: modify 
mechanism: by reference 
Value identifying the data stream that DCX$ANALYZE_DONE deletes. 
The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT initializes this value; you should not modify it. You 
can define multiple context arguments to identify multiple data streams 
that are processed simultaneously. 
CONDITION DCX$_INVCTX Error. The context variable is invalid, or the context 
a rror. The context variable is invalid, ex 
VALUES area is invalid or corrupted. This may be caused by 
RETURNED a failure to call the appropriate routine to initialize the 


context variable or by an application program error. 
DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by 
LIB$FREE_VM. 
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DCX$ANALYZE INIT Initialize Analysis Context 


The DCX$ANALYZE_INIT routine initializes the context area for a statistical 
analysis of the data records to be compressed. 








FORMAT DCX$ANALYZE INIT context [,item_code ,item_value] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS ~ context 
VMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 
Value identifying the data stream that DCX$ANALYZE_INIT initializes. 
The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT writes this context into the context argument; you 
should not modify its value. You can define multiple context arguments 
to identify multiple data streams that are processed simultaneously. 


item_code 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item code specifying information that you want DCX$ANALYZE_INIT to 
use in its analysis of data records and in its computation of the mapping 
function. DCX$ANALYZE_INIT reads this item_code argument, which is 
the address of the longword contained in the item code. 


For each item_code argument specified in the call, you must also specify a 
corresponding item_value argument. The item_value argument contains 
the interpretation of the item_code argument. 


The following symbolic names are the five legal values of the item_code 
argument: 


DCX$C_BOUNDED 
DCX$C_EST_BYTES 
DCX$C_EST_RECORDS 
DCX$C_LIST 
DCX$C_ONE_PASS 
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item_value 


VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Value of the corresponding item_code argument. DCX$ANALYZE_INIT 
reads the item_value argument, which is the address of a longword 
containing the item value. 


The item_code and item_value arguments always occur as a pair, and 
together they specify one piece of “advice” for the DCX routines to use in 
computing the map function. Note that, unless stated otherwise in the list 
of item codes and item values, no piece of “advice” is binding on DCX; that 
is, DCX is free to follow or not to follow the “advice.” 


The following table shows, for each item_code argument, the possible 
values for the corresponding item_value argument. 


Item Code Corresponding Item Value 


DCX$C_BOUNDED A Boolean variable. If bit <O> is true (equals 7), you 
are stating your intention to submit for analysis all data 
records that will be compressed; doing so often enables 
DCX to compute a better compression algorithm. If bit 
<0> is false (equals 0) or if the DCX$C_BOUNDED item 
code is not specified, DCX computes a compression 
algorithm without regard for whether all records to be 
compressed will also be submitted for analysis. 


DCX$C_EST_BYTES A longword value containing your estimate of the 
total number of data bytes that will be submitted for 
compression. This estimate is useful in those cases 
where fewer than the total number of bytes are presented 
for analysis. If you do not specify the DCX$C_EST_ 
BYTES item code, DCX submits for compression the 
same number of bytes that was presented for analysis. 
Note that you may specify DCX$C_EST_RECORDS or 
DCX$C_EST_BYTES, or both. 


DCX$C_EST_RECORDS _ A longword value containing your estimate of the 
total number of data records that will be submitted 
for compression. This estimate is useful in those 
cases where fewer than the total number of records 
are presented for analysis. If you do not specify the 
DCX$C_EST_RECORDS item code, DCX submits 
for compression the same number of bytes that was 
presented for analysis. 
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Item Code Corresponding Item Value 


DCX$C_LIST Address of an array of 2*n+1 longwords. The first 
longword in the array contains the value 2*n+1. The . 
remaining longwords are paired; there are n pairs. The 
first member of the pair is an item code, and the second 
member of the pair is the address of its corresponding 
item value. The DCX$C_LIST item code allows you to 
construct an array of item-code and item-value pairs 
and then to pass the entire array to DCX$ANALYZE_ 
INIT. This is useful when your language has difficulty 
interpreting variable-length argument lists. Note that the 
DCX$C_LIST item code may be specified, in a single 
call, alone or together with any of the other item-code 
and item-value pairs. 


DCX$C_ONE_PASS A Boolean variable. If bit <O> is true (equals 1), you 
make a binding request that DCX make only one 
pass over the data to be analyzed. If bit <O> is false 
(equals 0) or if the DCX$C_ONE_PASS item code is not 
specified, DCX may make multiple passes over the data, 
as required. Typically, DCX makes one pass. 





DESCRIPTION The DCX$ANALYZE_INIT routine initializes the context area for a 
statistical analysis of the data records to be compressed. The first (and 
typically the only) argument passed to DCX$ANALYZE_INIT is an integer 
variable to contain the context value. The data compression facility 
assigns a value to the context variable and associates the value with the 
created work area. Each time you want a record analyzed in that area, 
specify the associated context variable. You can analyze two or more files 
at once by creating a different work area for each file, giving each area 
a different context variable, and analyzing the records of each file in the 
appropriate work area. 





CONDITION ere 
VALUES DCX$_INVITEM Error; invalid item code. The number of arguments 
specified in the call was incorrect (this number should 
RETURNED be odd), or an unknown item code was specified. 
DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by LIB$GET_VM. 
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DCX$COMPRESS DATA Compress a Data Record 


The DCX$COMPRESS_DATA routine compresses a data record. You call this 
routine for each data record to be compressed. 





FORMAT 


DCX$COMPRESS DATA context ,in_rec,out_rec 
[,out_length] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Value identifying the data stream that DCX$COMPRESS_DATA 
compresses. The context argument is the address of a longword 
containing this value. DCX$COMPRESS_INIT initializes the value; 
you should not modify it. You can define multiple context arguments to 
identify multiple data streams that are processed simultaneously. 


in_rec 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 
Data record to be compressed. The in_rec argument is the address of the 
descriptor of the data record string. 


out_rec 

VMS usage: char_string 

type: character string 

access: write only 

mechanism: by descriptor 

Data record that has been compressed. The out_rec argument is the 
address of the descriptor of the compressed record that LIB$COMPRESS_ 
DATA returns. 
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out_length 


VMS usage: word_signed 

type: word integer (signed) 

access: write only 

mechanism: by reference 

Length (in bytes) of the compressed data record. The out_length 
argument is the address of a word into which LIBSCOMPRESS_DATA 
returns the length of the compressed data record. 





DESCRIPTION 


The DCX$COMPRESS_DATA routine compresses a data record. You call 
this routine for each data record to be compressed. As you compress 
each record, write the compressed record to the file containing the 
compression/expansion map. For each record, write the length of the 
record and substring string containing the record to the same file. See the 
COMPRESS DATA section in Example 5-1. 





CONDITION 
VALUES 
RETURNED 
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DCX$_INVCTX Error. The context variable is invalid, or the context 
area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize the 
context variable or by an application program error. 


DCX$_INVDATA Error. You specified the item value DCX$C_ 
BOUNDED in the DCX$ANALYZE_INIT routine 
and attempted to compress a data record (using 
DCX$COMPRESS_DATA) that was not presented for 
analysis (using DCX$ANALYZE_DATA). Specifying 
the DCX$C_BOUNDED item value means that 
you must analyze all data records that are to be 


compressed. 
DCX$_INVMAP Error; invalid map. The map argument was not 
specified correctly or the context area is invalid. 
DCX$_NORMAL Successful completion. 


DCX$_TRUNC Error. The compressed data record has been 
. truncated because the out_rec descriptor did not 
specify enough memory to accommodate the record. 


This routine also returns any condition values returned by 
LIB$ANALYZE_SDESC_R2 and LIB$SCOPY_R_DX. 
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DCX$COMPRESS DONE Specify Compression 
Complete 


The DCX$COMPRESS_DONE routine deletes the context area and sets the 
context variable to zero. 








FORMAT DCX$COMPRESS DONE context 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT context 
VMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 
Value identifying the data stream that DCX$COMPRESS_DONE deletes. 
The context argument is the address of a longword containing this value. 
DCX$COMPRESS_INIT writes the value into context; you should not 
modify its value. You can define multiple context arguments to identify 
multiple data streams that are processed simultaneously. 





DESCRIPTION ‘The DCX$COMPRESS_DONE routine deletes the context area and 
sets the context variable to zero, thus undoing the work of the 
DCX$COMPRESS_INIT routine. You call DCX$COMPRESS_DONE 
when all data records have been compressed (using DCX$COMPRESS_ 
DATA). After calling DCK$COMPRESS_DONE, call LIB$FREE_VM to 
free the virtual memory that DCX$MAKE_MAP used for the compression 
/expansion function. 





CONDITION eee 
VALUES DCX$_INVCTX Error. The context variable is invalid or the context 
area is invalid or corrupted. This may be caused by 
RETURNED a failure to call the appropriate routine to initialize the 
: context variable or by an application program error. 
DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by 
LIB$FREE_VM. 
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DCX$COMPRESS INIT Initialize Compression 
Context 


The DCX$COMPRESS_INIT routine initializes the context area for the 
compression of data records. 








FORMAT DCX$COMPRESS INIT context ,map 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS ~ context / 
VMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 
Value identifying the data stream that DCX$COMPRESS_INIT initializes. 

The context argument is the address of a longword containing this value. 
You should not modify the context value after DCX$COMPRESS_INIT 
initializes it. You can define multiple context arguments to identify 
multiple data streams that are processed simultaneously. 


map : 
VMS usage: address 

type: longword (unsigned) 

access: read only 


mechanism: by reference 
The function created by DCX$MAKE_MAP. The map argument is the 
address of the compression/expansion function’s virtual address. 


The map argument must remain at this address until data compression 
is completed and the context is deleted by means of a call to 
DCX$COMPRESS_DONE. 





DESCRIPTION The DCX$COMPRESS_INIT routine initializes the context area for the 
compression of data records. 


You call the DCX$COMPRESS_INIT routine after the call to ( 
DCX$ANALYZE_DONE. 
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CONDITION os 

VALUES DCX$_INVMAP Error; invalid map. The map argument was not 
specified correctly, or the context area is invalid. 

RETU RN E D DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by LIB$GET_VM 
and LIB$FREE_VM. 
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DCX$EXPAND_DATA Expand a Compressed Data 
Record 


The DCX$EXPAND_DATA routine expands (or restores) a compressed data 
record to its original state. 








FORMAT DCX$EXPAND DATA context ,in_rec ,out_rec 
[,out_length] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _ context 
VMS usage: context 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Value identifying the data stream that DCX$EXPAND_DATA expands. 
The context argument is the address of a longword containing this value. 
DCX$EXPAND_INIT initializes this value; you should not modify it. You 
can define multiple context arguments to identify multiple data streams 
that are processed simultaneously. 


in_rec 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 
Data record to be expanded. The in_rec argument is the address of the 
descriptor of the data record string. 


out_rec 

VMS usage: char_string 

type: character string 

access: write only 

mechanism: by descriptor 

Data record that has been expanded. The out_rec argument is 


the address of the descriptor of the expanded record returned by 
DCX$EXPAND_DATA. 
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out_length 

VMS usage: word_signed 

type: word integer (signed) 

access: write only 

mechanism: by reference 

Length (in bytes) of the expanded data record. The out_length argument 
is the address of a word into which DCX$EXPAND_DATA returns the 
length of the expanded data record. 





DESCRIPTION The DCX$EXPAND_DATA routine expands (or restores) a compressed 
data record to its original state. You call this routine for each data record 
to be expanded. 





CONDITION are 
VALUES DCX$_INVCTX Error. The context variable is invalid, or the context 
area is invalid or corrupted. This may be caused by 
RETURNED a failure to call the appropriate routine to initialize the 
context variable or by an application program error. 
DCX$_INVDATA Error. A compressed data record is invalid (probably 
truncated) and therefore cannot be expanded. 
DCX$_INVMAP Error; invalid map. The map argument was not 
specified correctly, or the context area is invalid. 
DCX$_NORMAL Successful completion. 
DCX$_TRUNC Warning. The expanded data record has been 


truncated because the out_rec descriptor did not 
specify enough memory to accommodate the record. 


This routine also returns any condition values returned by 
LIB$ANALYZE_SDESC_R2 and LIB$SCOPY_R_DX. 
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DCX$EXPAND_ DONE Specify Expansion Complete 


The DCX$EXPAND_DONE routine deletes the context area and sets the 
context variable to zero. 








FORMAT DCX$EXPAND_DONE context 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT context 
VMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 
Value identifying the data stream that DCX$EXPAND_DONE deletes. 
The context argument is the address of a longword containing this value. 
DCX$EXPAND_INIT initializes this value; you should not modify it. You 
can define multiple context arguments to identify multiple data streams 
that are processed simultaneously. 





DESCRIPTION The DCX$EXPAND_DONE routine deletes the context area and sets the 
context variable to zero, thus undoing the work of the DCX$EXPAND_ 
INIT routine. You call DCX$EXPAND_DONE when all data records have 
been expanded (using DCX$EXPAND_DATA). 





CONDITION ae dna 
VALUES DCX$_INVCTX Error. The context variable is invalid, or the context 
area is invalid or corrupted. This may be caused by 
RETURNED a failure to call the appropriate routine to initialize the 
context variable or by an application program error. 
DCX$NORMAL Successful completion. 


This routine also returns any condition values returned by 
LIB$FREE_VM. 
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DCX$EXPAND INIT Initialize Expansion Context 


The DCX$EXPAND_INIT routine initializes the context area for the expansion 
of data records. 








FORMAT DCX$EXPAND _INIT context ,map 
RETURNS VMS usage: cond_value 

type: longword (unsigned) — 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _~ context 
VMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 
Value identifying the data stream that DCX$EXPAND_INIT initializes. 
The context argument is the address of a longword containing this value. 
After DCX$EXPAND_INIT initializes this context value, you should not 
modify it. You can define multiple context arguments to identify multiple 
data streams that are processed simultaneously. 


map 

VMS usage: address 

type: longword (unsigned) 
access: read only 


mechanism: by reference 

Compression/expansion function (created by DCX$MAKE_MAP). The map 
argument is the address of the compression/expansion function’s virtual 
address. 


The map argument must remain at this address until data expansion is 
completed and context is deleted by means of a call to DCX$EXPAND_ 
DONE. 





DESCRIPTION The DCX$EXPAND_INIT routine initializes the context area for the 
expansion of data records. 


You call the DCX$EXPAND_INIT routine as the first step in the expansion 
(or restoration) of compressed data records to their original state. 
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Before you call DCX$EXPAND_INIT, read the length of the compressed file 
from the compression/expansion function (the map). Invoke LIB${GET_VM 
to get the necessary amount of storage for the function. LIB$GET_VM 
returns the address of the first byte of the storage area. 





CONDITION 

VALUES DCX$_INVMAP Error; invalid map. The map argument was not 
specified correctly, or the context area is invalid. 

RETURNED DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by LIB${GET_VM. 
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DCX$MAKE MAP Compute the 


Compression/Expansion 
Function 


The DCX$MAKE_MAP routine uses the statistical information gathered by 
DCX$ANALYZE_DATA to compute the compression/expansion function. 











FORMAT DCX$MAKE_MAP context ,map_adar [,map_size] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS ~— context 
VMS usage: context 
type: longword (unsigned) 
access: write only 


mechanism: by reference 

Value identifying the data stream that DCX$MAKE_MAP maps. The 
context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT initializes this value; you should not modify it. You 
can define multiple context arguments to identify multiple data streams 
that are processed simultaneously. 


map_addr 

VMS usage: address 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Starting address of the compression/expansion function. The map_addr 
argument is the address of a longword into which DCX$MAKE_MAP 
stores the virtual address of the compression/expansion function. 


map_size 

VMS usage: longword_signed 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Length of the compression/expansion function. The map_size argument 
is the address of the longword into which DCX$MAKE_MAP writes 

the length of the compression/expansion function. This is an optional 
argument. 


DCX-27 


Data Compression/Expansion (DCX) Routines 
DCX$MAKE_MAP 





DESCRIPTION The DCX$MAKE_MAP routine uses the statistical information gathered 
by DCX$ANALYZE_DATA to compute the compression/expansion function. 
In essence, this map is the algorithm used to shorten (or compress) the 
original data records as well as to expand the compressed records to their 
original form. 


The map must be available in memory when any data compression or 
expansion takes place; the address of the map is passed as an argument 
to the DCX$COMPRESS_INIT and DCX$EXPAND_INIT routines, which 


initialize the data compression and expansion procedures, respectively. 


The map is stored with the compressed data records, because the 
compressed data records are indecipherable without the map. When 
compressed data records have been expanded to their original state and 
no further compression is desired, you should delete the map using the 
LIB$FREE_VM routine. 


DCX requires that you submit data records for analysis and then call the 
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code, 
you must again submit data records for analysis (in the same order) and 
call DCX$MAKE_MAP again; on the second iteration, DOX$MAKE_MAP 
returns the DCX$_NORMAL status code. 





CONDITION . 

VALUES DCX$_AGAIN Informational. The map has not been created and the 
map_addr and map_size arguments have not been 

RETURNED written because further analysis is required. The data 


records must be analyzed (using DCX$ANALYZE_ 

DATA) again, and DCX$MAKE_MAP must be called 
again before DCX$MAKE_MAP will create the map 
and return the DCX$_ NORMAL status code. 


DCX$_INVCTX Error. The context variable is invalid, or the context 
area is invalid or corrupted. This may be caused by 
a failure to call the appropriate routine to initialize the 
context variable or by an application program error. 


DCX$_NORMAL Successful completion. 


This routine also returns any condition values returned by LIB$GET_VM 
and LIB$FREE_VM. 
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6.2 


EDT Routines 


On VMS operating systems, the EDT editor can be called from a program. 
Calling programs can be written in any VAX language that generates calls 
using the VAX Procedure Calling and Condition Handling Standard. 


You can set up your call to EDT so that the program handles all the 
editing work, or you can make EDT run interactively so that you can edit 
a file while the program is running. 


This chapter on callable EDT assumes that you know how to call an 
external facility from the language you are using. Callable EDT is a 
shareable image, which means that you save physical memory and disk 
space by having all processes access a single copy. 





Introduction to EDT Routines 


You must include a statement in your program accessing the EDT entry 
point. This reference statement is similar to a library procedure reference 
statement. The EDT entry point is referenced as EDT$EDIT. You can pass 
arguments to EDT$EDIT; for example, you can pass EDT$FILEIO or your 
own routine. When you refer to the routines you pass, call them FILEIO, 
WORKIO, and XLATE. Therefore, FILEIO can be either a routine provided 
by EDT (named EDT$FILEIO) or a routine that you write. 





Using EDT Routines: An Example 


Example 6-1 shows a VAX BASIC program that calls EDT. All three 
routines (FILEIO, WORKIO, and XLATE) are called. Note the reference to 
the entry point EDT$EDIT in line number 500. 
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6.2 Using EDT Routines: An Example 


Example 6-1 Using the EDT Routines in a VAX BASIC Program 


100 EXTERNAL INTEGER EDTSFILEIO 1 
200 EXTERNAL INTEGER EDTSWORKIO 

250 EXTERNAL INTEGER AXLATE 

300 EXTERNAL INTEGER FUNCTION EDTSEDIT 
400 DECLARE INTEGER RESULT 


450 DIM INTEGER PASSFILE(13) @ 
460 DIM INTEGER PASSWORK (13) 

465 DIM INTEGER PASSXLATE (1%) 

470 PASSFILE (0%) LOC (EDTSFILEIO) 
480 PASSWORK(0%) = LOC (EDTSWORKIO) 
485 PASSXLATE(0%) = LOC (AXLATE) 


500 RESULT = EDTSEDIT(’FILE.BAS’,’’,’EDTINI’,’’ ,0%, 3] 
PASSFILE(0%)BY REF, PASSWORK(0%) BY REF, 
PASSXLATE (0%) BY REF) 
600 IF (RESULT AND 1%) = 0% 
THEN 
PRINT “SOMETHING WRONG" 
CALL LIBSSTOP (RESULT BY VALUE) 
900 PRINT "EVERYTHING O.K." 
1000 END 


@ The external entry points EDT$FILEIO, EDT$WORKIO, and AXLATE 
are defined so that they can be passed to callable EDT. 


@ Arrays are used to construct the two-longword structure needed for 
data type BPV. 


© Here is the call to EDT. The input file is FILE.BAS, the output and 
journal files are defaulted, and the command file is EDTINI. A 0 is 
passed for the options word to get the default EDT options. 


© The array PASSFILE points to the entry point for all file I/O, which is 
set up in this example to be the EDT-supplied routine with the entry 
point EDT$FILEIO. Similarly, the array PASSWORK points to the 
entry point for all work I/O, which is the EDT-supplied routine with / 
the entry point EDT$WORKIO. \ 


@ PASSXLATE points to the entry point that EDT will use for all XLATE 
processing. PASSXLATE points to a user-supplied routine with the 
entry point AXLATE. 





6.3 EDT Routines 
The following pages describe the individual EDT routines. 
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EDT$EDIT Edit a File 


The EDT$EDIT routine invokes the EDT editor. 





FORMAT 


EDT$EDIT in_file [,out_file] [;com_file] [,jou_file] 
[,options] [, fileio] [,workio] [,xlate] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


in_file 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor 

File specification of the input file that EDT$EDIT is to edit. The in_file 
argument is the address of a descriptor pointing to this file specification. 
The string that you enter in this calling sequence is passed to the FILEIO 
routine to open the primary input file. This is the only required argument. 


out_file 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor 

File specification of the output file that EDT$EDIT creates. The out_file 
argument is the address of a descriptor pointing to this file specification. 
The default is that the input file specification is passed to the FILEIO 
routine to open the output file for the EXIT command. 


com_file 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor 

File specification of the startup command file to be executed when EDT is 
invoked. The com_file argument is the address of a descriptor pointing 
to this file specification. The com_file string is passed to the FILEIO 
routine to open the command file. The default is the same as that for EDT 
command file defaults. 
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jou_file 

VMS usage: char_string 

type: character-coded text string 
access: read only 


mechanism: by descriptor 

File specification of the journal file to be opened when EDT is invoked. 
The jou_file argument is the address of a descriptor pointing to this file 
specification. The jou_file string is passed to the FILEIO routine to open 
the journal file. The default is to use the same file name as in_file. 


options 

VMS usage: mask_longword 

type: aligned bit string 

access: read only 

mechanism: by reference 

Bit vector specifying options for the edit operation. The options argument 
is the address of an aligned bit string containing this bit vector. Only bits 
<5:0> are currently defined; all others must be 0. The default options have 
all bits set to 0. This is the same as the default setting when you invoke 
EDT to edit a file from DCL. 


Symbols and their descriptions follow: 


EDT$M_RECOVER If set, bit <O> causes EDT to read the journal file and 
execute the commands in it, except for the EXIT or QUIT 
commands, which are ignored. After the journal file 
commands are processed, editing continues normally. If 
bit <0> is set, the FILEIO routine is asked to open the 
journal file for both input and output; otherwise FILEIO 
is asked only to open the journal file for output. Bit <O> 
corresponds to the /RECOVER qualifier on the EDT 
command line. 


EDT$M_COMMAND If set, bit <i> causes EDT to signal if the startup command 
file cannot be opened. When bit <1> is 0, EDT intercepts 
the signal from the FILEIO routine indicating that the 
startup command file could not be opened. Then, EDT ' 
proceeds with the editing session without reading any 
startup command file. If no command file name is supplied 
with the call to the EDT$EDIT routine, EDT tries to open 
SYS$LIBRARY:EDTSYS.EDT or, if that fails, EDTINI.EDT. 
Bit <1> corresponds to the /COMMAND qualifier on the 
EDT command line. If EDT$M_NOCOMMAND (bit <4>) is 
set, bit <1> is overridden because bit <4> prevents EDT 
from trying to open a command file. 


EDT$M_NOJOURNAL If set, bit <2> prevents EDT from opening the journal file. 
Bit <2> corresponds to the /NOJOURNAL or /READ_ 
ONLY qualifier on the EDT command line. 


EDT Routines 
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EDT$M_NOOUTPUT If set, bit <3> prevents EDT from using the input file name 
as the default output file name. Bit <8> corresponds to 
the /NOOUTPUT or /READ_ONLY qualifier on the EDT 
command line. 

EDT$M_NOCOMMAND If set, bit <4> prevents EDT from opening a startup 
command file. Bit <4> corresponds to the /NOCOMMAND 
qualifier on the EDT command line. 


EDT$M_NOCREATE If set, bit <5> causes EDT to return to the caller if the 
input file is not found. The status returned is the error 
code EDT$_INPFILNEX. 


fileio 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: function call 


mechanism: by reference 

User-supplied routine called by EDT to perform file I/O functions. The 
fileio argument is the address of a bound procedure value containing 
the user-supplied routine. When you do not need to intercept any file 
I/O, either use the entry point EDT$FILEIO for this argument or omit 
it. When you only need to intercept some amount of file I/O, call the 
EDTS$FILEIO routine for the other cases. 


To avoid confusion, note that EDT$FILEIO is a routine provided by EDT 
whereas FILEIO is a routine that you provide. 


In order to accommodate routines written in high-level languages that do 
up-level addressing, this argument must have a data type of BPV (bound 
procedure value). BPV is a two-longword entity in which the first longword 
contains the address of a procedure entry mask and the second longword 
is the environment value. When the bound procedure is called, EDT loads 
the second longword into R1. If you use EDT$FILEIO for this argument, 
set the second longword to <0>. You can pass a <0> for the argument, 
and EDT will set up EDT$FILEIO as the default and set the environment 
word 


to 0. 

workio 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: function call 


mechanism: by reference 

User-supplied routine called by EDT to perform I/O between the work file 
and EDT. The workio argument is the address of a bound procedure value 
containing the user-supplied routine. Work file records are addressed only 
by number and are always 512 bytes long. If you do not need to intercept 
work file I/O, you can either use the entry point EDT$WORKIO for this 
argument or omit it. 


In order to accommodate routines written in high-level languages that do 
up-level addressing, this argument must have a data type of BPV (bound 
procedure value). This means that EDT loads R1 with the second longword 
addressed before calling it. If EDT$WORKIO is used for this argument, 
set the second longword to 0. You can pass a 0 for this argument, and EDT 
will set up EDT$WORKIO as the default and set the environment word 

to 0. 
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xlate 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: function call 


mechanism: by reference 

User-supplied routine that EDT calls when it encounters the nokeypad 
command XLATE. The xlate argument is the address of a bound procedure 
value containing the user-supplied routine. The XLATE routine allows you 
to gain control of your EDT session. If you do not need control of EDT 
during the editing session, you can either use the entry point EDT$XLATE 
for this argument or omit it. 


In order to accommodate routines written in high-level languages that do 
up-level addressing, this argument must have a data type of BPV (bound 
procedure value). This means that EDT loads R1 with the second longword 
addressed before calling it. If EDT$XLATE is used for this argument, set 
the second longword to 0. You can pass a 0 for this argument, and EDT 
will set up EDT$XLATE as the default and set the environment word to 0. 





DESCRIPTION 


If the EDT session is terminated by EXIT or QUIT, the status will be a 
successful value (bit <0> = 1). If the session is terminated because the file 
was not found and if the /(NOCREATE qualifier was in effect, the failure 
code EDT$_INPFILNEX is returned. In an unsuccessful termination 
caused by an EDT error, a failure code corresponding to that error is 
returned. Each error status from the FILEIO and WORKIO routines is 
explained separately. 


Three of the arguments to the EDT$EDIT routine, fileio, workio, and 
xlate are the entry point names of user-supplied routines. 





CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL Successful completion. 
EDT$_INPFILNEX /NOCREATE specified and input file does not exist. 


This routine also returns any condition values returned by user-supplied 
routines. 


FILEIO 


EDT Routines 
FILEIO 


The user-supplied FILEIO routine performs file I/O functions. You call it by 
specifying it as an argument in the EDT$EDIT routine. It cannot be called 
independently. 











FORMAT FILEIO code ,stream ,record ,rhb 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
A VMS status code that your FILEIO routine returns to EDT$EDIT. The 
fileio argument is a longword containing the status code. The only failure 
code that is normally returned is RMS$_EOF from a GET call. All other 
VMS RMS errors are signaled, not returned. The VMS RMS signal should 
include the file name and both longwords of the RMS status. Any errors 
detected with the FILEIO routine can be indicated by setting status to an 
error code. That special error code will be returned to the program by the 
EDT$EDIT routine. There is a special status value EDT$_NONSTDFIL 
for nonstandard file opening. 
Condition values are returned in RO. 

ARGUMENTS - code 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

A code from EDT that specifies what function the FILEIO routine is 
to perform. The code argument is the address of a longword integer 
containing this code. Following are the valid function codes: 


Function Code Description 


EDT$K_OPEN_INPUT The record argument names a file to be 
opened for input. The rhb argument is the 
default file name. 


EDT$K_OPEN_OUTPUT_SEQ The record argument names a file to be 
opened for output as a sequenced file. The 
rhb argument is the default file name. 


EDT$K_OPEN_OUTPUT_NOSEQ The record argument names a file to be 
opened for output. The rhb argument is the 
default file name. 
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Function Code Description 


EDT$K_OPEN_IN_OUT The record argument names a file to be 
opened for both input and output. The rhb 
argument is the default file name. 


EDT$K_GET The record argument is to be filled with data 
from the next record of the file. If the file has 
record prefixes, rhb is filled with the record 
prefix. If the file has no record prefixes, rhb 
is not written. When you attempt to read past 
the end of file, status is set to RMS$_EOF. 


EDT$K_PUT The data in the record argument is to be 
written to the file as its next record. If the file 
has record prefixes, the record prefix is taken 
from the rhb argument. For a file opened for 
both input and output, EDT$K_PUT is valid 
only at the end of the file, indicating that the 
record is to be appended to the file. 


EDT$K_CLOSE_DEL The file is to be closed and then deleted. The 
record and rhb arguments are not used in the 
call. 

EDT$K_CLOSE The file is to be closed. The record and rhb 
arguments are not used in the call. 

stream 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 


mechanism: by reference 

A code from EDT that indicates which file is being used. The stream 
argument is the address of a longword integer containing the code. 
Following are the valid codes. 


Function Code Description 


EDT$K_COMMAND FILE The command file. 
EDT$K_INPUT_FILE The primary input file. 


EDT$K_INCLUDE_FILE The secondary input file. Such a file is opened in 
response to an INCLUDE command. It is closed 
when the INCLUDE command is complete and will be 
reused for subsequent INCLUDE commands. 


EDT Routines 
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Function Code Description 


EDT$K_JOURNAL_FILE The journal file. If bit 0 of the options is set, it 
is opened for both input and output and is read 
completely. Otherwise, it is opened for output only. 
After it is read or opened for output only, it is used 
for writing. On a successful termination: of the editing 
session, the journal file is closed and deleted. EXIT 
/SAVE and QUIT/SAVE close the journal file without 


deleting it. 

EDT$K_OUTPUT_FILE The primary output file. It is not opened until you 
enter the EXIT command. 

EDT$K_WRITE_FILE The secondary output file. Such a file is opened 


in response to a WRITE or PRINT command. It is 
closed when the command is complete and will be 
reused for subsequent WRITE or PRINT commands. 


record 

VMS usage: char_string 

type: character-coded text string 
access: modify 


mechanism: by descriptor 

Text record passed by descriptor from EDT to the user-supplied FILEIO 
routine; the code argument determines how the record argument is 
used. The record argument is the address of a descriptor pointing to 
this argument. When the code argument starts with EDT$K_OPEN, the 
record is a file name. When the code argument is EDT$K_GRET, the 
record is a place to store the record that was read from the file. For code 
argument EDT$K_PUT, the record is a place to find the record to be 
written to the file. This argument is not used if the code argument starts 
with EDT$K_CLOSE. 


Note that for EDT$K_GET, EDT uses a dynamic or varying string 
descriptor; otherwise, EDT has no way of knowing the length of the 
record being read. EDT uses only string descriptors that can be handled 
by the Run-Time Library (RTL) routine STR$6COPY_DX. 


rhb 

VMS usage: char_string 

type: character-coded text string 
access: modify 


mechanism: by descriptor 

Text record passed by descriptor from EDT to the user-supplied FILEIO 
routine; the code argument determines how the rhb argument is used. 
When the code argument starts with EDT$K_OPEN, the rhb argument 
is the default file name. When the code is EDT$K_GET and the file has 
record prefixes, the prefixes are put in this argument. When the code 

is EDT$K_PUT and the file has record prefixes, the prefixes are taken 
from this argument. Like the record argument, EDT uses a dynamic or 
varying string descriptor for EDT$K_GET and uses only string descriptors 
that can be handled by the RTL routine STR6COPY_DX. 
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DESCRIPTION __ If you do not need to intercept any file I/O, you can use the entry point 
EDT$FILEIO for this argument or you can omit it. If you need to intercept 
only some file I/O, call the EDT$FILEIO routine for the other cases. 


When you use EDT$FILEIO as a value for the fileio argument, files are 
opened as follows: 


The record argument is always the RMS file name. 
The rhb argument is always the RMS default file name. 
There is no related name for the input file. 


The related name for the output file is the input file with OFP (output 
file parse). EDT passes the input file name, the output file name, or 
the name from the EXIT command in the record argument. 


The related name for the journal file is the input file name with the 
output file parse (OFP) RMS bit set. 


The related name for the INCLUDE file is the input file name with the 
OFP set. This is unusual because the file is being opened for input. 





CONDITION SS$_ NORMAL S ssful completi 
_ uccessTu} com ion. 
VALUES oe 
RETURN ED EDT$_NONSTDFIL File is not in standard text format. 
RMS$_EOF End of file on a GET. 
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The user-supplied WORKIO routine is called by EDT when it needs temporary 
storage for the file being edited. You'call it by specifying it as an argument in 
the EDT$EDIT routine. It cannot be called independently. 





FORMAT 


WORKIO code ,recordno ,record 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by immediate value 


Longword value returned as a VMS status code. It is generally a success 
code, because all VMS RMS errors should be signaled. The signal should 
include the file name and both longwords of the VMS RMS status. Any 
errors detected within work I/O can be indicated by setting status to an 
error code, which will be returned by the EDT$EDIT routine. 


The condition value is returned in RO. 





ARGUMENTS 


code 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

A code from EDT that specifies the operation to be performed. The code 
argument is the address of a longword integer containing this argument. 
The valid function codes are as follows: 


Function Code Description 


EDT$K_OPEN_IN_OUT Open the work file for both input and output. Neither the 


record nor recordno argument is used. 


EDT$K_GET Read a record. The recordno argument is the number 
of the record to be read. The record argument gives the 
location where the record is to be stored. 


EDT$K_PUT Write a record. The recordno argument is the number of 
the record to be written. The record argument tells the 
location of the record to be written. 


EDT$K_CLOSE_DEL Close the work file. After a successful close, the file is 
deleted. Neither the record nor recordno argument is 
used. 
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recordno 

VMS usage: longword_signed 

type: longword integer (signed) 
access: read only 


mechanism: by reference 

Number of the record to be read or written. The recordno argument is 
the address of a longword integer containing this argument. EDT always 
writes a record before reading that record. This argument is not used for 
open or close calls. 


record 

VMS usage: char_string 
type: character string 
access: modify 


mechanism: by descriptor 

Location of the record to be read or written. This argument always refers 
to a 512-byte string during GET and PUT calls. This argument is not used 
for open or close calls. 





DESCRIPTION Work file records are addressed only by number and are always 512 bytes 


long. If you do not need to intercept work file I/O, you can use the entry 
point EDT$WORKIO for this argument or you can omit it. 





CONDITION 
VALUE 
RETURNED 
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SS$_NORMAL Successful completion. 
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The user-supplied XLATE routine is called by EDT when it encounters the 
nokeypad command XLATE. You cause it to be called by specifying it as an 
argument in the EDT$EDIT routine. It cannot be called independently. 














FORMAT XLATE string 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword value returned as a VMS status code. It is generally a success 
code. If the XLATE routine cannot process the passed string for some 
reason, it sets status to an error code. Returning an error code from 
the XLATE routine aborts the current key execution and displays the 
appropriate error message. 
The condition value is returned in RO. 

ARGUMENT string 
VMS usage: char_string 
type: character-coded text string 
access: modify 
mechanism: by descriptor 
Text string passed to the nokeypad command XLATE. You can use the 
nokeypad command XLATE by defining a key to include the following 
command in its definition: 
XLATEtext*Z 
The text is passed by the string argument. The string argument is one 
that can be handled by the Run-Time Library (RTL) routine STR$COPY_ 
DX. 
This argument is also a text string returned to EDT. The string is made 
up of nokeypad commands that EDT is to execute. 

DESCRIPTION = The nokeypad command XLATE allows you to gain control of the EDT 


session. (See the VAX EDT Reference Manual for more information about 
the XLATE command.) If you do not need to gain control of EDT during 
the editing session, you can use the entry point EDT$XLATE for this 
argument or you can omit it. 
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CONDITION 
VALUE 
RETURNED 


SS$_NORMAL Successful completion. 
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This chapter describes the File Definition Language (FDL) routines. 
These routines perform many of the functions of the RMS File Definition 
Language. . 


7.1 Introduction to FDL Routines 


The FDL$CREATE routine is the one most likely to be called from a high- 
level language. It creates a file from an FDL specification and then closes 
the file. 


The following three FDL routines provide a way to specify all the options 
RMS allows when it executes create, open, or connect operations. They 
also allow you to specify special processing options required for your 
applications. 


The FDL$GENERATE routine produces an FDL specification by 
interpreting a set of RMS control blocks. It then writes the FDL 
specification either to an FDL file or to a character string. 


The FDL$PARSE routine parses an FDL specification, allocates RMS 
control blocks, and fills in the relevant fields. 


The FDL$RELEASE routine deallocates the virtual memory used by the 
RMS control blocks created by FDL$PARSE. 


These routines cannot be called from AST level. 


An FDL specification can be either in a file or in a character string. 
When specifying an FDL specification in a character string, delimit the 
statements of the FDL specification with semicolons. 


7.2 Using the FDL Routines: Examples 


Example 7—1 shows how to use the FDL$CREATE routine in a FORTRAN 
program. 
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Example 7-1 Using FDOL$CREATE in a FORTRAN Program 





* This program calls the FDLSCREATE routine. It 
* creates an indexed output file named NEW_MASTER.DAT 
* from the specifications in the FDL file named 
7 INDEXED.FDL. You can also supply a default filename 
is and a result name (that receives the name of the 
* created file). The program also returns all the 
is statistics. 
* 
IMPLICIT INTEGER* 4 (A - Z) 
EXTERNAL LIBSGET_LUN, FDLSCREATE 
CHARACTER IN_FILE*11 /' INDEXED.FDL’ /, 
1 OUT_FILE*14 /'NEW_MASTER.DAT’/, 
al DEF_FILE*11 /'DEFAULT.FDL’/, 
1 RES_FILE*50 
INTEGER* 4 FIDBLK (3) 70;0;07 
LS 


STATUS = FDLSCREATE (IN_FILE, OUT_FILE, 
DEF_FILE, RES FILE, FIDBLK, , ) 
IF (.NOT. STATUS) CALL LIBSSTOP (SVAL(STATUS) ) 


STATUS=LIBSGET_LUN(LOG_UNIT) 
OPEN (UNIT=LOG UNIT, FILE=RES FILE, STATUS=’ OLD’ ) 
CLOSE (UNIT=LOG_UNIT, STATUS=' KEEP’ ) 


WRITE (6,1000) (RES_FILE) 
WRITE (6,2000) (FIDBLK (I), I=1,3) 


1000 FORMAT (1X,’The result filename is: ’,A50) | 


2000 FORMAT (/1X,’FID-NUM: ’,I5/, 
1 LX,’ PID=SEQ: © 15/4 
1 1X,’FID-RVN: ’,15) 
END 





Example 7-2 shows how to use the FDL$PARSE and FDL$RELEASE 
routines in a MACRO program. 


Example 7-2 Using FDL$PARSE and FDL$RELEASE in a MACRO Program 





; This program calls the FDL utility routines FDLSPARSE and 

; FDLSRELEASE. First, FDLSPARSE parses the FDL specification 
+ PART.FDL. Then the data file named in PART.FDL is accessed 
; using the primary key. Last, the control blocks allocated 
; by FDLSPARSE are released by FDLSRELEASE. 





(continued on next page) 
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Example 7-2 (Cont.) Using FDL$PARSE and FDL$RELEASE in a MACRO Program 





-TITLE FDLEXAM 
v 
»-PSECT DATA, WRT, NOEXE 
a, 
MY_ FAB: . LONG 0 
MY_ RAB: LONG 0 
FDL FILE: -ASCID /PART.FDL/ ; Declare FDL file 
REC_SIZE=80 
LF=10 
REC_RESULT: .LONG REC SIZE 
-ADDRESS REC_BUFFER 
REC BUFFER: - BLKB REC SIZE 
HEADING: .ASCID /ID PART SUPPLIER COLOR / [EE] 
-PSECT CODE 
; Declare the external routines 
-EXTRN FDLSPARSE, - 
FDLSRELEASE 
ta 
- ENTRY FDLEXAM, “M<> ; Set up entry mask 
PUSHAL MY RAB ; Get set up for call with 
-PUSHAL MY_ FAB ; addresses to receive the 
PUSHAL FDL FILE ; FAB and RAB allocated by 
CALLS #3, G*FDLSPARSE ; FDLSPARSE 
BLBS RO, KEYO 
BRW ERROR 
KEYO: MOVL MY FAB,R10 ; Move address of FAB to R10 
MOVL MY_ RAB, R9 ; Move address of RAB to RQ 
MOVL #REC_SIZE, RABSW_USZ (RQ) 
MOVAB REC_BUFFER, RABSL_UBF (RQ) 
SOPEN FAB=(R10) ; Open the file 
BLBC RO, ERROR 
SCONNECT RAB= (RQ) ; Connect to the RAB 
BLBC RO, ERROR 
PUSHAQ HEADING ; Display the heading 
CALLS #1,G*LIBSPUT_ OUTPUT 
BLBC RO, ERROR 
GET_REC: $GET RAB= (R9) ; Get a record 
CMPL #RMS$_EOF, RO ; If not end of file, 
BEQLU CLEAN 7; continue 
BLBC RO, ERROR 
MOVZWL RABSW_RSZ(R9) ,REC_RESULT ; Move a record into 
PUSHAL REC_RESULT ; the buffer 
CALLS #1,G*LIBSPUT_OUTPUT ; Display the record 
BLBC RO, ERROR 
BRB GET_REC ; Get another record 
CLEAN: SCLOSE FAB=(R10) ; Close the FAB 
BLBC RO, ERROR 
PUSHAL MY_RAB ; Push RAB addr on stack 
PUSHAL MY FAB ; Push FAB addr on stack 
CALLS #2, G*FDLSRELEASE ; Release control blocks 
BLBC RO, ERROR 
BRB FINI 





(continued on next page) 
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Example 7-2 (Cont.) Using FDL$PARSE and FDL$RELEASE in a MACRO Program 


é 





ERROR: PUSHL 
CALLS 
SCLOSE 
RAB_ERROR: PUSHL 
PUSHL 
BRB 
FAB ERROR: PUSHL 
PUSHL 
RMS_ERR: CALLS 
BRB 
FINI: RET 


¢ 


RO " a. 
#1,G*LIBSSIGNAL 7 é 
FAB= (R10) 


RABSL_STV(R9) 
RABS$L_ STS (RQ) 
RMS_ERR 


FABSL_STV(R10) 
FABSL_ STS (R10) 


#2, G*LIBSSIGNAL 
FINI 


-END FDLEXAM 
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Example 7-3 shows how to use the FDL$PARSE and FDL$GENERATE 
routines in a VAX Pascal program. 


Example 7-3 Using FDL$PARSE and FDL$GENERATE in a VAX Pascal 
Program 





[INHERIT (’SYSSLIBRARY:STARLET’ ) ] 
PROGRAM FDLexample (input, output,order_ master) ; \ 


(* This program fills in its own FAB, RAB, and *) 
(* XABs by calling FDLSPARSE and then generates *) 
(* an FDL specification describing them. *) 
(* It requires an existing input FDL file *) 
(* (TESTING.FDL) for FDLSPARSE to parse. ) 
TYPE 

(*+ *) 
(* FDL CALL INTERFACE CONTROL FLAGS *) 
Ce *) 

$BIT1 = [BIT(1),UNSAFE] BOOLEAN; 


FDL2$TYPE = RECORD CASE INTEGER OF 

1: (FDL$ FDLDEF_BITS : [BYTE(1)] RECORD END; 
); 

2: (FDL$V_SIGNAL : [POS(0)] $BIT1; 


(* Signal errors; don’t return *) 
FDLSV_FDL_STRING : [POS(1)] $BIT1; 

(* Main FDL spec is a char string *) 
FDL$V_DEFAULT_STRING : [POS(2)] $BIT1; 

(* Default FDL spec is a char string *) 
FDLSV_FULL OUTPUT : [POS(3)] $BIT1; 

(* Produce a complete FDL spec *) 


FDLS$V_$CALLBACK : [POS(4)] $BIT1; 
(* Used by EDIT/FDL on input (DEC only) *) 
) 
END; 


(continued on next page) 


. 4 
File Definition Language (FDL) Routines 
7.2 Using the FDL Routines: Examples 


Example 7-3 (Cont.) Using FDL$PARSE and FDL$GENERATE in a VAX 
Pascal Program 





mail_order = RECORD 
order num : [KEY(0)] INTEGER; 
name : PACKED ARRAY[1..20] OF CHAR; 
address : PACKED ARRAY[1..20] OF CHAR; 
city : PACKED ARRAY[1..19] OF CHAR; 
state : PACKED ARRAY[1..2] OF CHAR; 
zip_code : [KEY(1)] PACKED ARRAY[1..5] 

OF CHAR; 

item_num : [KEY(2)] INTEGER; 
shipping : REAL; 
END; 


order file = [UNSAFE] FILE OF mail_order; 
ptr to FAB = “PABSTYPE; 
ptr to RAB = “RABSTYPE; 


byte = 0..255; 


VAR 
order_master : order file; 
flags : FDL2STYPE; 
order _rec : mail order; 
temp FAB : ptr_to_FAB; 
temp_RAB : ptr_to_RAB; 
status : integer; 


FUNCTION FDLSPARSE 
(SSTDESCR FDL FILE : PACKED ARRAY. [L..U: INTEGER] 
OF CHAR; 
VAR FAB PTR : PTR_TO FAB; 
VAR RAB PTR : PTR_TO RAB) : INTEGER; EXTERN; 


FUNCTION FDLSGENERATE 
(SREF FLAGS : FDL2STYPE; 
FAB PTR : PTR_TO FAB; 
RAB PTR : PTR_TO RAB; 
SSTDESCR FDL_FILE DST : PACKED ARRAY [L..U: INTEGER] 
OF CHAR) : INTEGER; 
EXTERN; 


BEGIN 


status := FDLSPARSE (’TESTING’, TEMP FAB, TEMP RAB); 
flags: :byte := 0; 
status := FDLSGENERATE (flags, 

temp_FAB, 

temp RAB, 

’SYSSOUTPOT:’ ); 








7.3 FDL Routines 
The following pages describe the individual FDL routines. 
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File Definition Language (FDL) Routines 
FDL$CREATE 


FDLS$CREATE Create a File from an FDL 
Specification and Close the 
File 


The FDL$CREATE routine creates a file from an FDL specification and then 
closes the file. 





FORMAT FDL$CREATE fal_desc [, filename] [,default_name] 
[,result_name] [,fid_block] [, flags] 
[,stmnt_num] [,retlen] [,sts] [stv] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _ fdl_desc 

VMS usage: char_string 
. type: character-coded text string 

access: read only 
mechanism: by descriptor—fixed-length string descriptor 
Name of a file that contains the FDL specification or the actual FDL 
specification to be parsed. The fdl_desc argument is the address of a 
character string descriptor pointing to this information. 


If the FDL$V_FDL_STRING flag is set in the mask argument, 
FDL$CREATE interprets this argument as an FDL specification in string 
form. Otherwise, FDL$CREATE interprets this argument as a file name. 


filename 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 

Name of the VMS RMS file to be created using the FDL specification. 
The filename argument is the address of a character string descriptor 
pointing to the VMS RMS file name. This name overrides the default_ 
name parameter given in the FDL specification. 


This argument is optional. 
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default_name 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 

Default name of the file to be created using the FDL specification. The 
default_name argument is the address of a character string descriptor 
pointing to the default file name. This name overrides any name given in 
the FDL specification. 


This argument is optional. 


result_name 

VMS usage: char_string 

type: character-coded text string 

access: write only 

mechanism: by descriptor—fixed-length string descriptor 

Resultant name of the file created by FDL$CREATE. The result_name 
argument is the address of a character string descriptor that receives the 
resultant file name. 


This argument is optional. 
fid_block 


VMS usage: vector_longword_unsigned 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

File identification of the VMS RMS file created by FDL$CREATE. The 
fid_block argument is the address of an array of longwords that receives 
the VMS RMS file identification information. The first longword contains 
the FID_NUM; the second contains the FID_SEQ; and the third contains 
the FID_RVN. They have the following definitions: 


FID_NUM The location of the file on the disk. Its value can range from 7 up to the 
number of files the disk can hold. 


FID_SEQ The file sequence number, which is the number of times the file number 
has been used. 


FID_RVN The relative volume number, which is the volume number of the volume 
on which the file is stored. If the file is not stored on a volume set, the 
relative volume number is 0. 


This argument is optional. 


flags 

VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference . 

Flags (or masks) that control how the fdl_dese argument is interpreted 
and how errors are signaled. The flags argument is the address of a 
longword containing the control flags (or a mask). If you omit this 
argument or specify it as zero, no flags are set. The table that follows 
shows the flags and their meanings. 
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Flag | Description 
FDL$V_FDL_STRING Interprets the fdl_desc argument as an FDL specification 


in string form. By default, the fdl_desc argument is 
interpreted as the file name of an FDL file. 


FDL$V_SIGNAL Signals any error. By default, the status code is returned 
to the calling image. 


This argument is optional. By default, an error status is returned rather 
than signaled. 


stmnt_num 


VMS usage: longword_unsigned 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

FDL statement number. The stmnt_num argument is the address of 
a longword that receives the FDL statement number. If the routine 
completes successfully, the stmnt_num argument is the number of 
statements in the FDL specification. If the routine does not complete 
successfully, the stmnt_num argument receives the number of the 
statement that caused the error. In general, however, line numbers and 
statement numbers are not the same. Null statements (blank lines) are 
not counted. Also, an FDL specification in string form has no “lines.” 


This argument is optional. 


retlen 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 
Number of characters returned in the result_name argument. The retlen 
argument is the address of a longword that receives this number. 


This argument is optional. 


sts 

VMS usage: longword_unsigned 
type: ~ longword_unsigned 
access: write only 


mechanism: by reference 

VMS RMS status value FAB$L_STS. The sts argument is the address of 
a longword that receives the VMS RMS status value FAB$L_STS from 
SYS$CREATE. 


stv 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 

VMS RMS status value FAB$L_STV. The stv argument is the address of 
a longword that receives the VMS RMS status value FAB$L_STV from 
SYS$CREATE. 


File Definition Language (FDL) Routines 


FDL$CREATE 








DESCRIPTION FDLS$CREATE calls the FDL$PARSE routine to parse the FDL 
specification. The FDL specification can be either in a file or a character 
string. FDL$CREATE opens (creates) the specified VMS RMS file, and 
then closes it without putting any data in it. 

FDL$CREATE does not create the output file if an error status is either 
returned or signaled. 

CONDITION SS$_NORMAL Normal successful completion 

ormal success mpletion. 

VALUES ; | oe 
FDL$_ABKW Ambiguous keyword in statement 

RETURNED ‘number’ <CRLF>’ reference-text’ . 


FDL$_ABPRIKW 


FDL$_BADLOGIC 
FDL$_CLOSEIN 
FDL$_CLOSEOUT 
FDL$_CREATE 
FDL$_CREATED 
FDL$_CREATED_STM 
FDL$_FDLERROR 
FDL$_ILL_ARG 
FDL$_INSVIREM 
FDL$_INVBLK 


FDL$_MULPRI 
FDL$_OPENFDL 
FDL$_OPENIN 
FDL$_OPENOUT 
FDL$_OUTORDER 


FDL$_READERR 
FDL$_RFLOC 
FDL$_SYNTAX 
FDL$_UNPRIKW 


FDL$_UNQUAKW 
FDL$_UNSECKW 


FDL$_VALERR 
FDL$_VALPRI 
FDL$_WARNING 


Ambiguous primary keyword in statement 
‘number’ <CRLF>’ reference-text’ . 


Internal logic error detected. 

Error closing ‘filename’ as input. 
Error closing ’ filename’ as output. 
Error creating ’ filename’. 
‘filename’ created. 

‘filename’ created in stream format. 
Error parsing FDL file. 

Wrong number of arguments. 
Insufficient virtual memory. 


Invalid VMS RMS control block at virtual address 
‘hex-offset’ . 


Multiple primary definition in statement ’ number’ . 
Error opening ‘filename’ . 

Error opening ‘filename’ as input. 

Error opening ‘filename’ as output. 


Key or area primary defined out of order in statement 
‘number’. 


Error reading ’ filename’ . 
Unable to locate related file. 
Syntax error in statement ‘number’ ’ reference-text’ . 


Unrecognized primary keyword in statement 
‘number’ <CRLF> ’ reference-text’ . 


Unrecognized qualifier keyword in statement 
‘number’ <CRLF> ‘ reference-text’ . 


Unrecognized secondary keyword in statement 
‘number’ <CRLF> ’ reference-text’ . 


Specified value is out of legal range. 
Value required on primary in statement ‘number’. 
Parsed with warnings. 


FDL-9 


File Definition Language (FDL) Routines 


FDL$CREATE 


FDL-10 


FDL$_WRITEERR 
RMS$_ACT 
RMS$_CRE 
RMS$_CREATED 
RMS$_DNF 
RMS$_DNR 
RMS$_EXP 
RMS$_FEX 
RMS$_FLK 
RMS$_PRV 
RMS$_SUPERSEDE 
RMS$_WLK 


Error writing ’ filename’. 

File activity precludes operation. 
ACP file create failed. 

File was created, not opened. 
Directory not found. 

Device not ready or not mounted. 


- File expiration date not yet reached. 


File already exists, not superseded. 

File currently locked by another user. 
Insufficient privilege or file protection violation. 
Created file superseded existing version. 
Device currently write locked. 


File Definition Language (FDL) Routines 
FDL$GENERATE 


FDL$GENERATE Generate an FDL Specification 


The FDL$GENERATE routine produces an FDL specification and writes it to 
either an FDL file or a character string. 





FORMAT FDL$GENERATE flags ,fab_pointer ,rab_pointer 
[,fdl_file_dst] [,fdl_file_resnam] 
[,fdl_str_dst] [,bad_blk_addr] 





[retlen] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
. access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ flags 
VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Flags (or masks) that control how the fdl_str_dst argument is interpreted 
and how errors are signalled. The flags argument is the address of 
a longword containing the control flags (or a mask). If you omit this 
argument or specify it as zero, no flags are set. The flags and their 
meanings are as follows: 


Flag Description 


FDL$V_FDL_STRING Interprets the fdl_str_dst argument as an FDL 
specification in string form. By default, the fdl_str_ 
dst argument is interpreted as a file name of an FDL file. 


FDL$V_FULL_OUTPUT Includes the FDL attributes to describe all the bits and- 
fields in the VMS RMS control blocks, including run- 
time options. If this flag is set, every VMS RMS field 
is inspected before being written. By default, only the 
FDL attributes that describe permanent file attributes are 
included (producing a much shorter FDL specification). 


FDL$V_SIGNAL Signals any error. By default, the status code is returned 
to the calling image. 

This argument is optional. By default, an error status is returned rather 

than signaled. 
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fab_pointer 

VMS usage: address 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

VMS RMS file access block (FAB). The fab_pointer argument is the 
address of a longword containing the address of a VMS RMS file access 
block (FAB). 


rab_pointer 

VMS usage: address 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

VMS RMS record access block (RAB). The rab_pointer argument is the 
address of a longword containing the address of a VMS RMS record access 
block (RAB). 


fdl_file_dst 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor 

Name of the FDL file to be created. The fdl_file_dst argument is the 
address of a character string descriptor containing the file name of the 
FDL file to be created. If the FDL$V_FDL_STRING flag is set in the flags 
argument, this argument is ignored; otherwise, it is required. The FDL 
specification is written to the file named in this argument. 


fdl_file_resnam 

VMS usage: char_string 

type: character-coded text string 

access: write only 

mechanism: by descriptor—fixed-length string descriptor 

Resultant name of the FDL file created. The fdl_file_resnam argument 
is the address of a variable character string descriptor that receives the 
resultant name of the FDL file created (if FDL$GENERATE is directed to 
create an FDL file). 


This argument is optional. 
fdl_str_dst 


VMS usage: char_string 

type: character-coded text string 

access: write only 

mechanism: by descriptor—fixed-length string descriptor 

FDL specification. The fdl_str_dst argument is the address of a variable 
character string descriptor that receives the FDL specification created. If 
the FDL$V_FDL_STRING bit is set in the flags argument, this argument 
is required; otherwise, it is ignored. 


File Definition Language (FDL) Routines 
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bad_blik_addr 


VMS usage: address 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of an invalid VMS RMS control block. The bad_blk_addr 
argument is the address of a longword that receives the address of an 
invalid VMS RMS control block. If an invalid control block (a fatal error) 
is detected, this argument is returned; otherwise, it is ignored. 


This argument is optional. 


retlen 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 

Number of characters received in either the fdl_file_resnam or the fdl_ 
str_dst argument. The retlen argument is the address of a longword that 
receives this number. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL 
FDL$_INVBLK 


RMS$_ACT 
RMS$_CONTROLC 
RMS$_CONTROLO 
RMS$_CONTROLY 
RMS$_DNR 
RMS$_EXT 
RMS$_OK_ALK 
RMS$_OK_DUP 
RMS$_OK_IDX 
RMS$_PENDING 
RMS$_PRV 
RMS$_REX 
RMS$_RLK 
RMS$_RSA 
RMS$_WLK 
SS$_ACCVIO 
STR$_FATINERR 
STR$_ILLSTRCLA 
STR$_INSVIRMEM 


Normal successful completion. 


Invalid VMS RMS control block at virtual address 
‘hex-offset’ . 


File activity precludes operation. 

Operation completed under CTRL/C. 

Output completed under CTRL/O. 

Operation completed under CTRL/Y. 

Device not ready or mounted. 

ACP file extend failed. 

Record already locked. 

Record inserted had duplicate key. 

Index update error occurred. 

Asynchronous operation pending completion. 
insufficient privilege or file protection violation. 
Record already exists. 

Target record currently locked by another stream. 
Record stream currently active. 

Device currently write locked. 

Access violation. 

Fatal internal error in Run-Time Library. 

illegal string class. 

Insufficient virtual memory. 
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FDL$PARSE Parse an FDL Specification 


The FDL$PARSE routine parses an FDL specification, allocates VMS RMS 
control blocks (FABs, RABs, or XABs), and fills in the relevant fields. 








FORMAT FDL$PARSE  /fdl_spec ,fdl_fab_pointer ,fdl_rab_pointer 
[flags] [,dflt_fdl_spc] [,stmnt_num] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS — fdl_spec 
VMS usage: char_string 
type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 
Name of the FDL file or the actual FDL specification to be parsed. The 
fdl_spec argument is the address of a character string descriptor pointing 
to either the name of the FDL file or the actual FDL specification to be 
parsed. If the FDL$V_FDL_STRING flag is set in the flags argument, 
FDL$PARSE interprets this argument as an FDL specification in string 
form. Otherwise, FDL$PARSE interprets this argument as a file name of 
an FDL file. 


fdl_fab_pointer 

VMS usage: address 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of an RMS file access block (FAB). The fdl_fab_pointer argument 

is the address of a longword that receives the address of an RMS file access 

ae (FAB). FDL$PARSE both allocates the FAB and fills in its relevant 
elds. 


fdil_rab_pointer 

VMS usage: address 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of an RMS record access block (RAB). The fdl_rab_pointer 
argument is the address of a longword that receives the address of an 
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RMS record access block (RAB). FDL$PARSE both allocates the RAB and 
fills in its relevant fields. 


flags 

VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Flags (or masks) that control how the dfit_fdl_spce argument is 
interpreted and how errors are signaled. The flags argument is the 
address of a longword containing the control flags. If you omit this 
argument or specify it as zero, no flags are set. The flags and their 
meanings are as follows: 


Flag Description 


FDL$V_DEFAULT_STRING Interprets the dflt_fdl_spe argument as an FDL 
specification in string form. By default, the dflt_fdl_ 
spe argument is interpreted as a file name of an 
FDL file. 


FDL$V_FDL_STRING Interprets the fdl_spec argument as an FDL 
specification in string form. By default, the fdl_ 
spec argument is interpreted as a file name of an 
FDL file. 


FDL$V_SIGNAL Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather 
than signaled. 


dfit_fdl_spc 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 

Name of the default FDL file or the default FDL specification itself. The 
dfit_fdl_spe argument is the address of a character string descriptor 
pointing to either the default FDL file or the default FDL specification. 
If the FDL$V_DEFAULT_STRING flag is set in the flags argument, 
FDL$PARSE interprets this argument as an FDL specification in string 
peepee FDL$PARSE interprets this argument as a file name of 
an e. 


This argument allows you to specify default FDL attributes. In other 
words, FDL$PARSE processes the attributes specified in this argument, 
unless you override them with the attributes you specify in the fdl_spec 


argument. 


You can code the FDL defaults directly into your program, typically with 
an FDL specification in string form. 


This argument is optional. 
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CONDITION 
VALUES 
RETURNED 
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stmnt_num 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

FDL statement number. The stmnt_num argument is the address of 
a longword that receives the FDL statement number. If the routine 
completes successfully, the stmnt_num argument is the number of 
statements in the FDL specification. If the routine does not complete 
successfully, the stmnt_num argument receives the number of the 
statement that caused the error. In general, however, line numbers and 
statement numbers are not the same. 


This argument is optional. By default, an error status is returned rather 
than signaled. 


SS$_NORMAL Normal successful completion. 

LIB$_ BADBLOADR Bad block address. 
LIB$_BADBLOSIZ Bad block size. 

LIB$_INSVIRMEM Insufficient virtual memory. 
RMS$_DNF Directory not found. 

RMS$_DNR Device not ready or not mounted. 
RMS$_WCC Invalid wildcard context (WCC) value. 
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FDL$RELEASE Free Virtual Memory Obtained By 


FDL$PARSE 


The FDL$RELEASE routine deallocates the virtual memory used by the VMS 
RMS control blocks created by FDL$PARSE. You must use FDL$PARSE 

to populate the contro! blocks if you plan to deallocate memory with 
FDLS$RELEASE later. 





FORMAT 


FDL$RELEASE  /fab_pointer] [,rab_pointer] [, flags] 
[,badblk_addr] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


fab_pointer 

VMS usage: address 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

File access block (FAB) to be deallocated using the LIB$FREE_VM 
system service. The fab_pointer argument is the address of a longword 
containing the address of the file access block (FAB). The FAB must be 
the same one returned by the FDL$PARSE routine. Any name blocks 
(NAMs) and extended attribute blocks (XABs) connected to the FAB are 
also released. 


This argument is optional. If you omit this argument or specify it as zero, 
the FAB (and any associated NAM blocks and XABs) is not released. 


rab_pointer 

VMS usage: address 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Record access block (RAB) to be deallocated using the LIB$FREE_VM 
system service. The rab_pointer argument is the address of a longword 
containing the address of the record access block (RAB). The address of 
the RAB must be the same one returned by the FDL$PARSE routine. Any 
XABs connected to the RAB are also released. 


This argument is optional. If you omit this argument or specify it as zero, 
the RAB (and any associated XABs) is not released. 
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flags 

VMS usage: mask_longword 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Flag (or mask) that controls how errors are signalled. The flags argument 
is the address of a longword containing the control flag (or a mask). If you 
omit this argument or specify it as zero, no flag is set. The flag is defined 
as follows: 


FDL$V_SIGNAL Signals any error. By default, the status code is returned to the 
calling image. 


This argument is optional. 


badblik_addr 


VMS usage: address 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of an invalid VMS RMS control block. The badblk_addr 
argument is the address of a longword that receives the address of an 
invalid VMS RMS control block. If an invalid control block (a fatal error) 
is detected, this argument is returned; otherwise, it is ignored. 





CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL Normal successful completion. 


FDL$_INVBLK Invalid VMS RMS control block at virtual address 
‘hex-offset’ . 


LIB$_BADBLOADR Bad block address. 

RMS$_ACT File activity precludes operation. 

RMS$_RNL Record not locked. 

RMS$_RSA Record stream currently active. ‘ 
SS$_ACCVIO Access violation. 


8 Librarian (LBR) Routines 


Libraries are files that provide a convenient way to organize frequently 
used modules of code or text. The librarian routines allow you to create 
and maintain libraries and their modules and to use the data stored in 
library modules. 


8.1 Introduction to LBR Routines 


You can also create and maintain libraries at the DCL level, using the 
DCL command LIBRARY. For details, see the VMS DCL Dictionary. 


8.1.1. Types of Library 


You can use the librarian routines to maintain the following types of 
library: 


Object libraries, which contain the object modules of frequently called 
routines. The VMS Linker Utility searches specified object module 
libraries when it encounters a reference it cannot resolve in one of its 
input files. For more information about how the linker uses libraries, 
see the description of the VMS Linker Utility in the VMS Linker 
Utility Manual. 


An object library has a default file type of OLB and defaults the file 
type of input files to OBJ. 


Macro libraries, which contain macro definitions used as input to the 
assembler. The assembler searches specified macro libraries when it 
encounters a macro that is not defined in the input file. See the VAX 
MACRO and Instruction Set Reference Manual for information about 
defining macros. 


A macro library has a default file type of MLB and defaults the file 
type of input files to MAR. 


Help libraries, which contain modules of help messages that provide 
user information about a program. You can retrieve help messages 

at DCL level by executing the DCL command HELP, or in your 
program by calling the appropriate librarian routines. For information 
about creating help modules for insertion into help libraries, see the 
description of the Librarian Utility in the VMS Librarian Utility 
Manual. 


A help library has a default file type of HLB and defaults the file type 
of input files to HLP. 


Text libraries, which contain any sequential record files that you 
want to retrieve as data for a program. For example, some compilers 
can retrieve program source code from text libraries. Each text 

file inserted into the library corresponds to one library module. 
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Your programs can retrieve text from text libraries by calling the 
appropriate librarian routines. 


A text library has a default file type of TLB and defaults the file type 
of input files to TXT. 


e Shareable image libraries, which contain the symbol tables of 
shareable images used as input to the linker. For information about 
how to create a shareable image library, see the descriptions of the 

- Librarian and Linker Utilities in the VMS Librarian Utility Manual 
and the VMS Linker Utility Manual. 


A shareable image library has a default type of OLB and defaults the 
file type of input files to EXE. 


¢ User-developed libraries, which have characteristics specified when you 
call the LBR$OPEN routine to create a new library. User-developed 
libraries allow you to use the librarian routines to create and maintain 
libraries that are not structured in the form assigned by default to 
the other library types. Note that you cannot use the DCL command 
LIBRARY to access user-developed libraries. 


8.1.2 Structure of Libraries 
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You create libraries by executing the DCL command LIBRARY or by 
calling the LBR$OPEN routine. When object, macro, text, help, or 
shareable image libraries are created, the Librarian Utility structures 
them as described in Figures 8-1 and 8-2. You can create user-developed 
libraries only by calling LBR$OPEN; they are structured as described in 
Figure 8-3. 


Library Headers 


Every library contains a library header that describes the contents of 

the library, for example, its type, size, version number, creation date, and 
number of indexes. You can retrieve data from a library's header by calling 
the LBR$GET_HEADER routine. 


8.1.2.2 Modules 


Each library module consists of a header and data. The data is the 

data you inserted into the library; the header associated with the data 

is created by the librarian routine and provides information about the 
module, including its type, attributes, and date of insertion into the library. 
You can read and update a module’s header by calling the LBR$SET_ 
MODULE routine. 


Indexes and Keys 


Libraries contain one or more indexes, which can be thought of as 
directories of the library’s modules. The entries in each index are keys, 
and each key consists of a key name and a module reference. The module 
reference is a pointer to the module’s header record and is called that 
record’s file address (RFA). Macro, text, and help libraries (see Figure 8-1) 
contain only one index, called the module name table. The names of the 
keys in the index are the names of the modules in the library. 
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Object and shareable image libraries (see Figure 8-2) contain two indexes: 
the module name table and a global symbol table. The global symbol table 
consists of all the global symbols defined in the modules in the library. 
Each global symbol is a key in the index and points to the module in 
which it was defined. 


If you need to point to the same module with several keys, you should 
create a user-developed library, which can have up to eight indexes 
(see Figure 8-3). Each index consists of keys that point to the library’s 
modules. 


The librarian routines differentiate library indexes by numbering them, 
starting with 1. For all but user-developed libraries, the module name 
table is index number 1 and the global symbol table, if present, is index 
number 2. You number the indexes in user-developed libraries. When you 
access libraries that contain more than one index, you may have to call 
LBR$SET_INDEX to tell the librarian routines which index to use. 


Figure 8-1 Structure of a Macro, Text, or Help Library 


Library Header 


Index (Module Name Table) 


Each key in the index points to a module. 










Modules 
Data Data 
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Figure 8-2 Structure-of an Object or Shareable Image Library 


Library Header 


Index (Module Name Table) 


Each key in the index points to a module. 











Index (Global Symbol Table) 


Global Global Global Global Global 
Symbol Symbol Symbol Symbol Symbol 


Each global symbol is a key in the index, and points to the module in 
which it was defined. 










Modules 
Data 
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Figure 8-3 Structure of a User-Developed Library 


Library Header 


Index 


Each key in an index points to one module. More than one key (from 
the same or a different index) may point to the same module. 







Can have up to 
8 indexes. 

















index 
Modules 
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8.1.2.4 Summary of Routines 
All the librarian routines begin with the characters LBR$. Your programs 
can call these routines by using the VMS Procedure Calling and Condition 
Handling Standard, which is documented in the Introduction to VMS 
System Routines. When you call a librarian routine, you must provide 
whatever arguments the routine requires; when the routine completes 
execution, it returns a status value to your program. In addition to the 
condition values listed with the descriptions of each routine, some routines 
may return the success code SS$_ NORMAL as well as various RMS or 
SS error codes. When you link programs that contain calls to librarian 
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routines, the linker locates the routines during its default search of 
SYS$SHARE:LBRSHR. 


The following table lists the routines and summarizes their functions. 


Routine Name 


LBR$CLOSE 
LBR$DELETE_DATA 
LBR$DELETE_KEY 
LBR$FIND 


LBR$FLUSH 


LBR$GET_HEADER 
LBR$GET_HELP 
LBR$GET_HISTORY 


LBRSGET_INDEX 
LBR$GET_RECORD 
LBRSINI_CONTROL 


LBRSINSERT_KEY 
LBR$LOOKUP_KEY 
LBRSOPEN 
LBRSOUTPUT_HELP 


LBRSPUT_END 


LBR$PUT_HISTORY 
LBR$PUT_RECORD 


LBRSREPLACE_KEY 
LBR$RET_RMSSTV 
LBR$SEARCH 
LBR$SET_INDEX 


LBR$SET_LOCATE 
LBRS$SET_MODULE 
LBRSSET_MOVE 


Function 


Closes an open library. 
Deletes a specified module’s header and data, 
Deletes a key from a library index. 


Finds a module by using an address returned by a 
preceding call to LBR$LOOKUP_KEY. 


Writes the contents of modified blocks to the library file and 
returns the virtual memory that contained those blocks. 


Retrieves information from the library header. 
Retrieves help text from a specified library. 


Retrieves library update history records and calls a user- 
supplied routine with each record returned. 


Calls a routine to process modules associated with some or 
all of the keys in an index. 


Reads a data record from the module associated with a 
specified key. 


Initializes a control index that the librarian uses to identify a 
library. 


Inserts a new key in the current library index. 
Looks up a key in the current index. 
Opens an existing library or creates a new one. 


Retrieves help text from an explicitly named library or from 
user-supplied default libraries, and optionally prompts you 
for additional help queries. 


Terminates a sequence of records written to a module with 
LBR$PUT_RECORD. 


Inserts a library update history record. 


Writes a data record to the module associated with the 
specified key. 


Replaces an existing key in the current library index. 
Returns the last VMS RMS status value. 
Finds index keys that point to specified data. 


Sets the index number to be used during processing of the 
library. 


Sets librarian subroutine record access to locate mode. 
Reads and optionally updates a module header. 
Sets librarian subroutine record access to move mode. 
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8.2 Using the LBR Routines: Examples 


This section provides programming examples that show how to call LBR$ 
routines to create a library, insert a module into a library, extract a module 
from a library, and delete a module from a library. Although the examples 
do not use all of the librarian routines, they do provide an introduction to 
the data structures needed and the calling syntax required to use any of 
the routines. 


For each library you want to work with, you must call LBR$INI_ 
CONTROL and LBR$OPEN before calling any other routine (except 
LBR$SOUTPUT_HELP). 


When you call LBR$INI_CONTROL, this routine sets up a control index 
(do not confuse this with a library index) that is used, in the calls to the 
other librarian routines, to identify the library to which the routine applies 
(because you may want your program to work with more than one library 
at a time). LBR$INI_CONTROL also specifies whether you want to create, 
read, or modify the library. 


After you call LBR$INI_CONTROL, you call LBR$OPEN to open the 
library and specify its type. When you finish working with a library, 
you should call LBR$CLOSE to close it. Remember to call LBR$INI_ 
CONTROL again, if you want to reopen the library. LBR$CLOSE 
deallocates all the memory associated with the library including the 
control index. The order in which you call the routines between 
LBR$OPEN and LBR$CLOSE depends upon the library operations 

you need to perform. You may want to call LBR$LOOKUP_KEY or 
LBR$GET_INDEX to find a key, then perform some operation on the 
module associated with the key. You can think of a module as being both 
the module itself and its associated keys. To access a module, you first 
need to access a key that points to it; to delete a module, you first need to 
delete any keys that point to it. 


The examples are written in VAX Pascal. In VAX Pascal, all data items, 
functions (such as the librarian routines), and procedures must be 
declared at the beginning of the program. Following the declarations 

is the executable section, which performs the actions of the program. The 
executable section makes extensive use of the structured control constructs 
IF-THEN-ELSE and WHILE-condition-DO. Note that code between a 
BEGIN END pair is treated as a unit. 


The listing of each example contains many comments (any code between a 

pair of asterisks (* *) is a comment), and each listing is followed by notes 

about the program. The highlighted numbers in the notes are keyed to the 
highlighted numbers in the examples. 


Example 8—1 illustrates the use of LBR routines to create a new library. 
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Example 8-1 Creating a New Library Using VAX Pascal 





PROGRAM createlib (INPUT, OUTPUT) ; 
(*This program creates a text library*) 
(*Data type of*) 

Create Array = ARRAY [1..20] OF INTEGER; (*create options array*) 
(*Constants and return status error 
codes for LBR$_ OPEN & LBRSINI_CONTROL. 
These are defined in $LBRDEF macro*) 

LBR$C_CREATE, LBR$C_TYP_TXT,LBR$_ILLCREOPT, LBR$_ILLCTL, 

LBR$_ILLFMT, LBR$ NOFILNAM, LBR$_OLDMISMCH, LBR$_TYPMISMCH 


[EXTERNAL] INTEGER; 
(*Create options array codes. These 


are defined in SCREDEF macro*) 
CRESL_TYPE, CRE$L_KEYLEN, CRESL_ ALLOC, CRE$L_IDXMAX, CRES$L_ENTALL, 
CRESL LUHMAX, CRE$L_VERTYP, CRESL_IDXOPT,CRESC_MACTXTCAS, 


TYPE 


VAR 


CRES$C_VMSV3 : [EXTERNAL] INTEGER; 

Lib Name : VARYING [128] OF CHAR; (*Name of library to create*) 

Options : Create Array; (*Create options array*) 

File Type PACKED ARRAY [1..4] (*Character string that is default*) 
OF CHAR := ’.TLB’; (*file type of created lib file*) 

lib_index_ptr : UNSIGNED; (*Value returned in library init*) 

status UNSIGNED; (*Return Status for function calls*) 


(*-*-*-*—-Function and Procedure Definitions—*-*-*-*) 
(*Function that returns library 
control index used by librarian*) 


FUNCTION LBRSINI_CONTROL (VAR library index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR nambik: ARRAY[1..u: INTEGER] 
OF INTEGER := %SIMMED 0): 


INTEGER; EXTERN; 
(*Function that creates/opens library*) 


FUNCTION LBRSOPEN (library index: UNSIGNED; 
fns: [class_s]PACKED ARRAY[1..u: INTEGER] OF CHAR; 
create options: Create_Array; 
dns: [CLASS _S] PACKED ARRAY [13..u3:INTEGER] OF CHAR; 
rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %SIMMED 0; 
rns: [CLASS _S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 

SIMMED 0; 
VAR rnslen: INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that closes library*) 
FUNCTION LBRSCLOSE (library index: UNSIGNED) : 


INTEGER; EXTERN; 
(*Error handler to check error codes 


if open/create not successful*) 





(continued on next page) 
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Example 8-1 (Cont.) Creating a New Library Using VAX Pascal 





PROCEDURE Open_Error; 4 ) 
BEGIN 
WRITELN (‘Open Not Successful’); (*Now check specific error codes*) 
IF status = IADDRESS(LBR$ _ILLCREOPT) THEN 
WRITELN (/ Create Options Not Valid Or Not Supplied’); 
IF status = IADDRESS(LBR$_ILLCTL) THEN 
WRITELN (/ Invalid Library Index’); 
IF status = IADDRESS(LBR$_ ILLFMT) THEN 
WRITELN (’ Library Not In Correct Format’); 
IF status = IADDRESS(LBRS$_NOFILNAM) THEN 
WRITELN (’ Library Name Not Supplied’); 
IF status = IADDRESS(LBR$ OLDMISMCH) THEN 
WRITELN (’ Old Library Conflict’); 
IF status = IADDRESS (LBR$_TYPMISMCH) THEN 
WRITELN (/ Library Type Mismatch’ ) 
END; (*of procedure Open _Error*) 
BEGIN (* KKKKKKKKKKKKKKK DECLARATIONS COMPLETE KKEKKEKKEKKKKKEKKKEKEKKEKKRKEKKEK 
KRKKKKKKKKKKEKKE MAIN PROGRAM BEGINS HERE KREEKKKKKEKKKKEKKKEKKEKEK *) 
(*Prompt for Library Name*) 
WRITE (/Library Name: '’); READLN(Lib Name); 
(*Fill Create Options Array. Divide 
by 4 and add 1 to get proper subscript*) 


Options [IADDRESS (CRESL_TYPE) DIV 4 + 1] := IADDRESS (LBRS$C_TYP_TXT) ; 
Options [IADDRESS (CRESL_KEYLEN) DIV 4 + 1] := 31; 5 ] 

Options [IADDRESS(CRESL_ALLOC) DIV 4 +1] := 8; 

Options [IADDRESS (CRE$L_IDXMAX) DIV 4 + 1] := 1; 

Options [IADDRESS (CRES$L_ENTALL) DIV 4 + 1] := 96; 

Options [IADDRESS (CRESL_LUHMAX) DIV 4 + 1] := 20; 

Options [IADDRESS (CRESL_VERTYP) DIV 4 + 1] := IADDRESS (CRESC_VMSV3) ; 
Options [IADDRESS (CRE$L_IDXOPT) DIV 4 + 1] := IADDRESS(CRESC_MACTXTCAS) ; 


(*Initialize library control index*) 
status := LBRSINI_CONTROL (lib_index ptr, 


IADDRESS (LBR$C_CREATE) , (*Create access*) 
IADDRESS (LBRS$C_TYP_TXT) ); (*Text library*) 
IF NOT ODD(status) THEN (*Check return status*) 
WRITELN (‘Initialization Failed’ ) 
ELSE (*Initialization was successful*) 
BEGIN (*Create and open the library*) 
status := LBRSOPEN (lib index ptr, 
Lib Name, 
Options, 7] 
File Type) ; 
IF NOT ODD(status) THEN (*Check return status*) 
Open_Error (*Call error handler*) 8 
ELSE (*Open/create was successful*) 
BEGIN (*Close the library*) 


status := LBRSCLOSE(lib_index_ptr); 
IF NOT ODD(status) THEN (*Check return status*) 
WRITELN (‘Close Not Successful’ ) 
END 
END 
END. (*of program creatlib*) 





_Each item in the following list corresponds to a number highlighted in 
Example 8-1. 
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@ To gain access to these LBR$ symbols in your program, write the 
following two-line MACRO program: 


SLBRDEF GLOBAL 
. END 


Then assemble the program into an object module by executing the 
command: 


MACRO program-name 


Finally, link the resultant object module with the object module created 
when your source program is compiled or assembled. (Note: Pascal 
programmers alternatively may use the INHERIT attribute to include 
these symbols from SYS$LIBRARY:STARLET.PEN.) 


@ To gain access to the CRE$ symbols, write a two-line MACRO program 
as described in item 1, substituting $CREDEF for $LBRDEF. 


© Start the declarations of the librarian routines that are used by the 
program. Each argument to be passed to the librarian is specified 
on a separate line and includes the name (which just acts as a 
placeholder) and data type (for example: UNSIGNED, which means an 
unsigned integer value, and PACKED ARRAY OF CHAR, which means 
a character string). If the argument is preceded by VAR, then a value 
for that argument is returned by the librarian to the program. 


@ Declare the procedure Open_Error, which is called in the executable 
section if the librarian returns an error when LBR$OPEN is called. 
Open_Error checks the librarian’s return status value to determine the 
specific cause of the error. The return status values for each routine 
are listed in the descriptions of the routines. 


Initialize the array called Options with the values the librarian needs 
to create the library. 


Call LBR$INI_CONTROL, specifying that the function to be performed 
is create and that the library type is text. 


Call LBR$OPEN to create and open the library; pass the Options 
array initialized in item 5 to the librarian. 


If the call to LBR$OPEN was unsuccessful, call the procedure Open_ 
Error (see item 4) to determine the cause of the error. 


Example 8-2 illustrates the use of LBR routines to insert a new module 
into a library. 
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Example 8-2 Inserting a Module Into a Library Using VAX Pascal 





PROGRAM insertmod (INPUT, OUTPUT) ; 
(*This program inserts a module into a library*) 

TYPE 
Rfa_Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 

VAR 
LBRS$C_UPDATE, (*Constants for LBRSINI_CONTROL*) 
LBRS$C_TYP_TXT, (*Defined in $LBRDEF macro*) 
LBRS$_KEYNOTFND : [EXTERNAL] INTEGER; (*Error code for LBRSLOOKUP_KEY*) 
Lib Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 
Module Name : VARYING [31] OF CHAR; (*Name of module to insert*) 
Text_Data_Record : VARYING [255] OF CHAR; (*Record in new module*) 
Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 


lib_index_ptr : UNSIGNED; (*Value returned in library init*) 
status : UNSIGNED; (*Return status for function calls*) 
CxXtrila ptr 2 Rfa Ptr; (*For key lookup and insertion*) 

Key Not Found : BOOLEAN := FALSE; (*True if new mod not already in 1ib*) 


(*-*-*-*-Function Definitions-*-*-*-*) 
(*Function that returns library 
control index used by librarian*) 
FUNCTION LBRSINI_CONTROL (VAR library index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER := @IMMED 0): 
INTEGER; EXTERN; 
(*Function that creates/opens library*) 
FUNCTION LBRSOPEN (library index: UNSIGNED; 
fns: [class_s]PACKED ARRAY[1l..u: INTEGER] OF CHAR; 
create options: ARRAY [12..u2:INTEGER] OF INTEGER := 
SIMMED 0; 
dns: [CLASS _S] PACKED ARRAY [13..u3: INTEGER] OF CHAR 
:= %IMMED 0; 
rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
SIMMED 0; 
VAR rnslen: INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that finds a key in index*) 
FUNCTION LBRSLOOKUP_KEY (library index: UNSIGNED; 
key name: [CLASS _S] PACKED ARRAY [1l..u: INTEGER] OF 
CHAR; 
VAR txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 
(*Function that inserts key in index*) 
FUNCTION LBRSINSERT_KEY (library index: UNSIGNED; 
key name: [CLASS _S] PACKED ARRAY [l..u: INTEGER] OF 
CHAR; 
txtrfa: Rfa_ Ptr): 


INTEGER; EXTERN; 
(*Function that writes data records*) 





(continued on next page) 
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Example 8-2 (Cont.) Inserting a Module Into a Library Using VAX Pascal 





FUNCTION LBRSPUT_RECORD (library index: UNSIGNED; (*to modules*) 
textline: [CLASS S] PACKED ARRAY [l..u: INTEGER] OF 
CHAR; 


txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 
(*Function that marks end of a module*) 
FUNCTION LBRSPUT_END (library index: UNSIGNED) : 
INTEGER; EXTERN; 
(*Function that closes library*) 
FUNCTION LBRSCLOSE (library index: UNSIGNED) : 
INTEGER; EXTERN; 
BEGIN (* KEEKKKKKKKEKEKKEKEE DECLARATIONS COMPLETE KKEEKKKKEKKKKEKKKREKKKKEKRKEKEKE 
KKEKKKKKKKKEKKKKK MAIN PROGRAM BEGINS HERE KKEKKKKKEKEKKKKKKEKKKKEKEK *) 
(*Prompt for library name and 
module to insert*) 
WRITE (‘Library Name: ’); READLN(Lib Name); 
WRITE (‘Module Name: ’); READLN (Module Name) ; 
(*Initialize lib for update access*) 


status := LBRSINI_CONTROL (lib index ptr, 
IADDRESS (LBR$C_UPDATE), (*Update access*) 
IADDRESS(LBRS$C_TYP_TXT)); (*Text library*) 
IF NOT ODD(status) THEN (*Check error status*) 
WRITELN (’ Initialization Failed’) 
ELSE (*Initialization was successful*) 
BEGIN 
status := LBRSOPEN (lib _index_ptr, (*Open the library*) ; 
Lib Name) ; , 
IF NOT ODD(status) THEN (*Check error status*) 
WRITELN (‘Open Not Successful’) 
ELSE (*Open was successful*) 
BEGIN (*Is module already in the library?*) 
status := LBRSLOOKUP_KEY (lib_index ptr, 


Module Name, 
txtrfa_ptr); 
IF ODD(status) THEN (*Check status. Should not be odd*) 
WRITELN (‘Lookup key was successful.’, 
‘The module is already in the library.’) 
ELSE (*Did lookup key fail because key not found?*) 
IF status = IADDRESS (LBR$_KEYNOTFND) THEN @ 
Key Not_Found := TRUE 


a 


END 
END; 





(continued on next page) 
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Example 8-2 (Cont.) Inserting a Module Into a Library Using VAX Pascal 


(*****k*TF LBRSLOOKUP_KEY failed because the key was not found 
(as expected), we can open the file containing the new module, 
and write the module’s records to the library file*****x*) 
IF Key Not Found THEN 
BEGIN 
OPEN (Textin, Module_Name, old) ; 
RESET (Textin) ; 


WHILE NOT EOF (Textin) DO (*Repeat until end of file*) 
BEGIN 
READ (Textin, Text_Data_Record) ; (*Read record from 
external file*) 
status := LBRSPUT_RECORD (lib index ptr, (*Write*) 
Text_Data_Record, (*record to*) 
txtrfa_ptr); (*library*) 


IF NOT ODD(status) THEN 
WRITELN (’Put Record Routine Not Successful’ ) 
END; (*of WHILE statement*) 
IF ODD(status) THEN (*True if all the records have been 
successfully written into the library*) 
BEGIN 
status := LBRS$PUT_END (lib _index_ ptr); (*Write end of 
module record*) 
IF NOT ODD(status) THEN 
WRITELN (’Put End Routine Not Successful’ ) 
ELSE (*Insert key for new module*) 
BEGIN 
status := LBRSINSERT_KEY (lib index ptr, 
Module Name, 
txtrfa_ ptr); 
IF NOT ODD(status) THEN 
WRITELN (’Insert Key Not Successful’ ) 
END 
END 
END; 
status := LBRSCLOSE(lib index ptr); 
IF NOT ODD(status) THEN 
WRITELN (’Close Not Successful’ ) 
END. (*of program insertmod*) 





Each item in the following list corresponds to a number highlighted in 
Example 8-2. 


@ Call LBR$INI_CONTROL, specifying that the function to be performed 
is update and that the library type is text. 


@ Call LBR$LOOKUP_KEY to see whether the module to be inserted is 
already in the library. 


© Call LBR$LOOKUP_KEY to see whether the lookup key failed because 
. the key was not found. (In this case, the status value is LBR$_ 
KEYNOTFEND.) 


@ Read a record from the input file, then use LBR$PUT_RECORD to 
write the record to the library. When all the records have been written 
to the library, use LBR$PUT_END to write an end of module record. 
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© Use LBR$INSERT_KEY to insert a key for the module into the current 
index. 


Example 8-3 illustrates the use of LBR routines to extract a module from 
a library. 


Example 8-3 Extracting a Module from a Library Using VAX Pascal 





PROGRAM extractmod (INPUT, OUTPUT, Textout) ; 
(*This program extracts a module from a library*) 
TYPE 
Rfa_Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 
VAR 


LBRS$C_UPDATE, (*Constants for LBRSINI_CONTROL*) 
LBRSC_TYP TXT, (*Defined in $LBRDEF macro*) 
RMS$_EOF : [EXTERNAL] INTEGER; (*RMS return status; defined in 


SRMSDEF macro*) 
Lib Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 
Module Name : VARYING [31] OF CHAR; (*Name of module to insert*) 


Extracted_File : VARYING [31] OF CHAR; (*Name of file to hold 
extracted module*) 

Outtext : PACKED ARRAY [1..255] OF CHAR; (*Extracted mod put here, *) 

Outtext2 : VARYING [255] OF CHAR; (* then moved to here*) 

i: INTEGER; (*For loop control*) 

Textout : FILE OF VARYING [255] OF CHAR; (*File containing extracted 
module*) 

nullstring : CHAR; (*nullstring, pos, and len used to*) 

pos, len : INTEGER; (*find string in extracted file recd*) 

lib _index_ptr : UNSIGNED; (*Value returned in library init*) 

status : UNSIGNED; (*Return status for function calils*) 

txtrfa_ptr : Rfa_Ptr; (*For key lookup and insertion*) 


(*-*-*-*-Function Definitions—*—*-*-*) 
(*Function that returns library 
control index used by librarian*) 
FUNCTION LBRSINI_CONTROL (VAR library index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that creates/opens library*) 
FUNCTION LBRSOPEN (library index: UNSIGNED; 
fns: [class_s]PACKED ARRAY[1..u: INTEGER] OF CHAR; 
create options: ARRAY [12..u2:INTEGER] OF INTEGER : 
SIMMED 0; 
dns: [CLASS _S] PACKED ARRAY [13..u3: INTEGER] OF CHAR 
:= SIMMED 0; 
vlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS_S] PACKED ARRAY [15..u5: INTEGER] OF CHAR := 
SIMMED 0; 
VAR rnslen: INTEGER := SIMMED 0): 
INTEGER; EXTERN; 
(*Function that finds a key in an index”) 
FUNCTION LBRS$LOOKUP_KEY (library index: UNSIGNED; 
key name: [CLASS S] PACKED ARRAY [l..u: INTEGER] OF 
CHAR; 
VAR txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 





(continued on next page) 
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Example 8-3 (Cont.) Extracting a Module from a Library Using VAX Pascal 





(*Function that retrieves records from modules*) 
FUNCTION LBRSGET_RECORD (library index: UNSIGNED; 
var textline: [CLASS S] PACKED ARRAY [1..u: INTEGER] OF 
CHAR) : 
INTEGER; 
EXTERN; 
(*Function that closes library*) 
FUNCTION LBRSCLOSE (library index: UNSIGNED) : 
INTEGER; EXTERN; 
BEGIN (* KEEKKKKKKKKEKEKKE DECLARATIONS COMPLETE KREKEKKKKEKKKKKKKKKKKKEKKKEKKEEK 
KRREEKKKKKKKKKEKKK MAIN PROGRAM BEGINS HERE KKKEKKKKKEKKKKEKKKKKKKKKEK *) 
(* Get Library Name, Module To Extract, And File To Hold Extracted Module *) 
WRITE (’Library Name: ’); READLN(Lib Name) ; 
WRITE (‘Module Name: ‘'); READLN(Module_ Name) ; 
WRITE (’Extract Into File: ’); READLN(Extracted_File); 


status := LBRSINI_CONTROL (lib_index_ptr, 0 
IADDRESS (LBR$C_UPDATE) , 
IADDRESS (LBR$C_TYP_TXT)); 
IF NOT ODD(status) THEN 
WRITELN (’ Initialization Failed’ ) 


ELSE 
BEGIN 
status := LBRSOPEN (lib index ptr, 
Lib Name) ; 
IF NOT ODD(status) THEN 
WRITELN (‘Open Not Successful’) 
ELSE 
BEGIN 2] 
status := LBRSLOOKUP_KEY (lib index _ptr, 
Module Name, 
. txtrfa_ptr); 
IF NOT ODD(status) THEN 
WRITELN (‘Lookup Key Not Successful’ ) 
ELSE 
BEGIN 13] 
OPEN (Textout, Extracted File, new) ; 
REWRITE (Textout) 
END 
END 
END; 
WHILE ODD(status) DO 
BEGIN 
nullstring := ’’ (0); 
FOR i := 1 TO 255 DO 4) 
Outtext{i] := nullstring; 
status := LBRSGET_RECORD (lib _index_ptr, 


Outtext); 
IF NOT ODD(status) THEN 
BEGIN 5 ] 
IF status = IADDRESS (RMS$_EOF) THEN 
WRITELN (/ RMS end of file’) 
END 





(continued on next page) 
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Example 8-3 (Cont.) Extracting a Module from a Library Using VAX Pascal 


ELSE 
BEGIN © 
pos := INDEX(Outtext, nullstring); (*find first null 
in Outtext*) 
len := pos - 1; (*length of Outtext to first null*) 
IF len >= 1 THEN 
BEGIN 
Outtext2 := SUBSTR(Outtext,1, LEN); 
WRITE (Textout, Outtext2) 
END 
END 
END; (*of WHILE*) 
status := LBRSCLOSE(lib_ index ptr); 
IF NOT ODD(status) THEN 
WRITELN (’Close Not Successful’) 
END. (*of program extractmod*) 


Each item in the following list corresponds to a number highlighted in 
Example 8-3. 


@ Call LBR$INI_CONTROL, specifying that the function to be performed 
is update and that the library type is text. 


Call LBR$LOOKUP_KEY to find the key that points to the module you 
want to extract. : 


Open an output file to receive the extracted module. 


Initialize the variable that is to receive the extracted records to null 
characters. 


Call LBR$GET_RECORD te see if there are more records in the file 
(module). A failure indicates that the end of the file has been reached. 


Write the extracted record data to the output file. This record should 
consist only of the data up to the first null character. 


Example 8—4 illustrates the use of LBR routines to delete a library. 


Po iii. a 
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8.2 Using the LBR Routines: Examples 


Example 8-4 Deleting a Module from a Library Using VAX Pascal 





PROGRAM deletemod (INPUT, OUTPUT) ; 
(*This program deletes a module from a library*) 
TYPE 
Rfa_Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 
VAR 


LBRS$C_UPDATE, (*Constants for LBRSINI_CONTROL*) 
LBRSC_TYP_TXT, (*Defined in $LBRDEF macro*) 
LBR$_KEYNOTFND : [EXTERNAL] INTEGER; (*Error code for LBRSLOOKUP_KEY*) 
Lib Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 


Module Name : VARYING [31] OF CHAR; (*Name of module to insert*) 
Text_Data_Record : VARYING [255] OF CHAR; (*Record in new module*) 
Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 


lib_index_ ptr : UNSIGNED; (*Value returned in library init*) 
status : UNSIGNED; (*Return status for function calls*) 
txtria ptr : Rea. Ptr; (*For key lookup and insertion*) 

Key Not_Found : BOOLEAN := FALSE; (*True if new mod not already in lib*) 


(*-*-*—*-Function Definitions—*—-—*-*-*) 
(*Function that returns library 
control index used by librarian*) 
FUNCTION LBRSINI_CONTROL (VAR library index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER := %IMMED 0): 
INTEGER; EXTERN; 
(*Function that creates/opens library*) 
FUNCTION LBRSOPEN (library_index: UNSIGNED; 
fns: [class _s]PACKED ARRAY[{1..u: INTEGER] OF CHAR; 
create options: ARRAY [12..u2:INTEGER] OF INTEGER := 
SIMMED 0; 
dns: [CLASS _S] PACKED ARRAY [13..u3:INTEGER] OF CHAR 
:= SIMMED 0; 
rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS _S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
SIMMED 0; 
VAR rnslen: INTEGER := SIMMED 0): 
INTEGER; EXTERN; 
(*Function that finds a key in index*) 
FUNCTION LBR$LOOKUP_KEY (library index: UNSIGNED; 
key name: [CLASS S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 
VAR txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 
(*Function that removes a key from an index*) 
FUNCTION LBRSDELETE_KEY (library index: UNSIGNED; 
key name: [CLASS _S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR) : 
INTEGER; 
EXTERN; 





(continued on next page) 
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Example 8-4 (Cont.) Deleting a Module from a Library Using VAX Pascal 





(*Function that deletes all the records 
associated with a module*) 
FUNCTION LBRSDELETE DATA (library index: UNSIGNED; 
txtrfa: Rfa_Ptr): 
INTEGER; 
EXTERN; 
(*Function that closes library*) 
FUNCTION LBRSCLOSE (library index: UNSIGNED) : 
INTEGER; EXTERN; 


BEGIN (* **xkxkkkkKKAKKKA DECLARATIONS COMPLETE * * KI KKK KEK IK KK 
KkKAKKKAKAKAKKAKK MATN PROGRAM BEGINS HERE ***XRKAKKAKKKKKKKKKKKE *) 
(* Get Library Name and Module to Delete *) 
WRITE(’Library Name: '); READLN (Lib Name) ; 
WRITE (’Module Name: '); READLN (Module Name) ; 
(*Initialize lib for update access*) 





status := LBRSINI_CONTROL (lib index ptr, 
IADDRESS (LBR$C_UPDATE), (*Update access*) 
TADDRESS (LBR$C_TYP_TXT)); (*Text library*) 
IF NOT ODD(status) THEN (*Check error status*) 
WRITELN (‘Initialization Failed’ ) 
ELSE (*Initialization was successful*) 
BEGIN 
status := LBRSOPEN (lib _index_ptr, (*Open the library*) 
Lib Name) ; 
IF NOT ODD(status) THEN (*Check error status*) 
WRITELN (’Open Not Successful’) 
ELSE (*Open was successful*) 
BEGIN @ (*Is module in the library?*) 
status := LBRSLOOKUP_KEY (lib_index_ptr, 


Module Name, 

txtrfa_ptr); 

IF NOT ODD(status) THEN (*Check status*) 
WRITELN(’ Lookup Key Not Successful’) 


END 
END; 
IF ODD(status) THEN (*Key was found; delete it*) 
BEGIN 
status := LBRSDELETE_KEY (lib index ptr, 3 ] 


Module Name) ; 
IF NOT ODD(status) THEN 
WRITELN (’Delete Key Routine Not Successful’) 
ELSE (*Delete key was successful*) 
BEGIN (*Now delete module’s data records*) 
status := LBRSDELETE_ DATA (lib_index_ptr, 
txtrfa_ptr); 
IF NOT ODD(status) THEN 
WRITELN(’Delete Data Routine Not Successful’ ) 
END 
END; 
status := LBRSCLOSE(lib index ptr); (*Close the library*) 
IF NOT ODD(status) THEN 
WRITELN (‘’Close Not Successful’); 
END. (*of program deletemod*) 
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Each item in the following list corresponds to a number highlighted in 
Example 8-4. 


@ Call LBR$INI_CONTROL, specifying that the function to be performed 
is update and the library type is text. 


@ Call LBR$LOOKUP_KEY to find the key associated with the module 
you want to delete. 

© Call LBR$DELETE_KEY to delete the key associated with the module 
you want to delete. If more than one key points to the module, you 
need to call LBR$LOOKUP_KEY and LBR$DELETE_KREY for each 
key. 

@ Call LBR$DELETE_DATA to delete the module (the module header 
and data) from the library. 





8.3 LBR Routines 
The following pages describe the individual LBR routines. 
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LBR$CLOSE 


LBR$CLOSE Close a Library 


The LBR$CLOSE routine closes an open library. 





FORMAT 


LBR$CLOSE __library_index 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 





DESCRIPTION When you are finished working with a library, you should call 


LBR$CLOSE to close it. Upon successful completion, LBR$CLOSE closes 
the open library and deallocates all of the memory used for processing it. 





CONDITION 
VALUES 
RETURNED 
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LBR$_ILLCTL Specified library control index not valid. 
LBR$ LIBNOTOPN Specified library not open. 


Librarian (LBR) Routines 
LBRSDELETE_DATA 


LBR$DELETE DATA Delete a Module’s Data 


The LBR$DELETE_DATA routine deletes the module header and data 
associated with the specified module. 





FORMAT 


LBR$DELETE_DATA /ibrary_index , txtrfa 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


txirfa 


VMS usage: vector_longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Record’s file address (RFA) of the module header for the module you want 
to delete. The txtrfa argument is the address of the 2-longword array that 
contains the RFA. You can obtain the RFA of a module header by calling 
LBR$LOOKUP_exit KEY or LBR$PUT_RECORD. 





DESCRIPTION 


If you want to delete a library module, you must first call LBR$DELETE_ 
KEY to delete any keys that point to it. If no library index keys are 
pointing at the module header, LBR$DELETE_DATA deletes the module 
header and associated data records; otherwise, this routine returns the 
error LBR$_STILLKEYS. 


Note that other librarian routines may reuse data blocks that contain no 
data. 
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CONDITION a . 

VALUES LBR$_ILLCTL pian: library Salis index not valid. 
LBR$_INVRFA Specified RFA not valid. 

RETURNED LBR$_LIBNOTOPN Specified library not open. 
LBR$_STILLKEYS Keys in other indexes still point at the module header. 


Therefore, the specified module was not deleted. 
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LBR$DELETE_KEY Delete a Key 


The LBR$DELETE_KEY routine deletes a key from a library index. 











FORMAT LBR$DELETE_KEY /ibrary_index ,key_name 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS __ /ibrary_index 


VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of a longword containing the 
index. 


key_name 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Key to be deleted from the library index. For libraries with binary 
keys, the key_name argument is the address of an unsigned longword 
containing the key number. 


For libraries with ASCII keys, the key_name argument is the address 
of the string descriptor pointing to the key with the following argument 
characteristics. 


Argument 

Characteristics Entry 

VMS Usage Char_string 
Type Character string 
Access Read only 
Mechanism By descriptor 
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DESCRIPTION _ If LBR$DELETE_KEY finds the key specified by key_name in the current 
index, it deletes the key. Note that, if you want to delete a library module, 
you should first use LBR$DELETE_KEY to delete any keys that point 
to it, then use LBR$DELETE_DATA to delete the module’s header and 


associated data. 


You cannot call LBR$DELETE_KEY from within the user-supplied routine 
specified in LBR$SEARCH or LBR$GET_INDEX. 





CONDITION LBR$_ILLCTL 
VALUES 1 A Vs Iara res. 
RETURNED LBRS_KEYNOTFND 


LBR$_LIBNOTOPN 
LBR$_UPDURTRAV 
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Specified library control index not valid. 
Specified key not found. 
Specified library not open. 


Specified index update not valid in a user-supplied 
routine specified in LBRSSEARCH or LBR$GET_ 
INDEX. 


Librarian (LBR) Routines 
LBRS$FIND 


LBR$FIND Look Up a Module by Its RFA 


The LBR$FIND routine sets the current internal read context for the library to 
the library module specified. 





FORMAT 


LBR$FIND /ibrary_index , txtrfa 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


txtrfa 


VMS usage: vector_longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

RFA (record’s file address) of the module header for the module you want 
to access. The txtrfa argument is the address of a 2-longword array 
containing the RFA. You can obtain the RFA of a module header by calling 
LBR$LOOKUP_KEY or LBR$PUT_RECORD. 





DESCRIPTION 


You use the LBR$FIND routine to access a module that you had accessed 
earlier in your program. For example, if you look up several keys with 
LBR$LOOKUP_KEY, you can save the RFAs returned by LBR$LOOKUP_ 
KEY and later use LBR$FIND to reaccess the modules. Thus, you do not 
have to look up the module header’s key every time you want to access the 
module. If the specified RFA is valid, LBR$FIND initializes internal tables 
so that you can read the associated data. 
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LBRSFIND 

CONDITION ae 
LBR$_ILLCTL Specified library control index not valid. 

VALUES i ; 

RETURNED LBR$_INVRFA Specified RFA not valid. 
LBR$_LIBNOTOPN Specified library not open. 
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LBR$FLUSH Recover Virtual Memory 


The LBR$FLUSH routine writes modified blocks back to the library file and 
frees the virtual memory the blocks had been using. 





FORMAT 


LBRS$FLUSH /ibrary_index ,block_type 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_LCONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


block_type 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by value 

Extent of the flush operation. The block_type argument contains the 
longword value that indicates how the flush operation proceeds. If you 
specify LBR$C_FLUSHDATA, the data blocks are flushed. If you specify 
LBR$C_FLUSHALL, first the data blocks and then the current library 
index are flushed. 


The LBR$ symbols LBR$C_FLUSHDATA and LBR$C_FLUSHALL are 
defined in the macro $LBRDEF (found in SYS$LIBRARY:STARLET.MLB), 
which must be assembled and then linked with your program. 





DESCRIPTION 


LBR$FLUSH cannot be called from other librarian routines that reference 
cache addresses or by routines called by librarian routines. 
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LBR$FLUSH 
CONDITION . 
VALUES LBR$ NORMAL Operation completed successfully. 
LBR$_BADPARAM Error. A value passed to the LBR$FLUSH routine was 
RETURNED either out of range or an illegal value. 
LBR$_WRITERR Error. An error occurred during the writing of the 


cached update blocks to the library file. 
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LBR$GET_HEADER Retrieve Library Header 


Information 


The LBR$GET_HEADER routine returns information from the library’s header 
to the caller. 











FORMAT LBR$GET_HEADER /ibrary_index ,retary 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENTS __ /ibrary_index 


VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The — 
library_index argument is the address of the longword that contains the 
index. 


retary 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 

Array of 128 longwords that receives the library header. The retary 
argument is the address of the array that contains the header 
information. The information returned in the array is listed in the 
following table (the symbols are defined by the $LHIDEF macro in 
SYS$LIBRARY:STARLET.MLB). 


Offset in 

Longwords Symbolic Name Contents 

0 LHI$L_TYPE Library type (see LBRSOPEN for possible 
values) 

1 LHI$L_NINDEX Number of indexes 

2 LHI$L_MAJORID Library format major identification 

3 LHI$L_MINORID Library format minor identification 
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Offset in 
Longwords 


32-128 


Symbolic Name 


LHI$T_LBRVER 
LHI$L_CREDAT 
LHI$L_UPDTIM 
LHI$L_UPDHIS 
LHI$L_FREEVBN 
LHI$L_FREEBLK 
LHI$B_NEXTRFA 


LHI$L_NEXTVBN 


LHI$L_FREIDXBLK 


LHI$L_FREEIDX 
LHI$L_HIPREAL 
LHI$L_IDXBLKS 
LHI$L_IDXCNT 

LHI$L_MODCNT 


LHI$L_MHDUSZ 


LHI$L_MAXLUHREC 
LHI$L_NUMLUHREC 


LHI$L_LIBSTATUS 


Contents 


ASCIC version of Librarian 
Creation date/time 

Date/time of last update 

VBN of start of update history 
First logically deleted block 
Number of deleted biocks 


Record’s File Address (RFA) of end of 
library 


Next VBN to allocate at end of file 
Number of free preallocated index blocks 
Listhead for preallocated index blocks 
VBN of highest preallocated block 
Number of index blocks in use 

Number of index entries (total) 

Number of entries in index 1 (module 


names) 


Number of bytes of additional information 
reserved in module header 


Maximum number of library update history 
records maintained 


Number of library update history records in 
history 


Library status (false if there was an error 
closing the library) 


Reserved by Digital 








DESCRIPTION On successful completion, LBR$GET_HEADER places the library header 
information into the array of 128 longwords. 
Note that the offset is the byte offset of the value into the header 
structure. You can convert the offset to a longword subscript by 
dividing the offset by 4 and adding 1 (assuming that subscripts in your 
programming language begin with 1). 

CONDITION LBR$_LIBNOTOPN Specified lib t 

ecified library not open. 
VALUES LBR$_ILLCTL nana fears ae index not valid 
RETURNED ~ | 
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LBR$GET HELP Retrieve Help Text 


The LBR$GET_HELP routine retrieves help text from a help library, displaying 
it on SYS$OUTPUT or calling your routine for each record returned. 





FORMAT 


LBR$GET_HELP /ibrary_index [, line_width] [, routine] 
[data] [| key_1][|}key_2... ,key_10] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_LCONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


line_width 

VMS usage: longword_signed 

type: longword (signed) 

access: read only 

mechanism: by reference 

Width of the help text line. The line_width argument is the address of a 
longword containing the width of the listing line. If you do not supply a 
a width or if you specify 0, the line width defaults to 80 characters per 
ine. 


routine 

VMS usage: procedure 

type: procedure entry mask 
access: read only 


mechanism: by reference 
Routine called for each line of text you want output. The routine 
argument is the address of the entry mask for this user-written routine. 


If you do not supply a routine argument, LBR$GET_HELP calls the 
Run-Time Library procedure LIB$PUT_OUTPUT to send the help text 
lines to the current output device (SYS$OUTPUT). However, if you want 
SYS$OUTPUT for your program to be a disk file rather than the terminal, 
you should supply a routine to output the text. 


LBR-31 


Librarian (LBR) Routines 


LBR$GET_HELP 


LBR-32 


The routine you specify is called with an argument list of four longwords: 7 


1. The first argument is the address of a string descriptor for the output © 
line. 


2 The second argument is the address of an unsigned longword 
containing flag bits that describe the contents of the text being passed. 
The possible flags are as follows: 

HLP$M_NOHLPTXT Specified help text cannot be found. 

HLP$M_KEYNAMLIN Text contains key names of the printed text. 

HLP$M_OTHERINFO Text is part of the information provided on additional 
help available. 


(The $HLPDEF macro in SYS$LIBRARY:STARLET.MLB defines these 
flag symbols.) 


Note that, if no flag bit is set, help text is passed. 


3 The third argument is the address stipulated in the data argument 
specified in the call to LBR$GET_HELP (or the address of a 0 constant 
if the data argument is zero or was omitted). 


4 The fourth argument is a longword containing the current key level. 


The routine you specify must return with success or failure status. A 
failure status (low bit = 0) terminates the current call to LBR$GET_HELP. 


data 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 
Data passed to the routine specified in the routine argument. The data 
argument is the address of data for the routine. The address is passed to 
the routine specified in the routine argument. If you omit this argument 
or specify it as zero, then the argument passed in your routine will be the 
address of a zero constant. 


key_1,key_2,...,key_10 

VMS usage: longword_signed 

type: longword (signed) 

access: read only 

mechanism: by descriptor 

Level of the help text to be output. Each key_1,key_2, ... ,key_10 
argument is the address of a descriptor pointing to the key for that level. 


If the key_1 descriptor is 0 or if it is not present, LBR$GET_HELP 
assumes that the key_1 name is HELP, and it ignores all the other keys. 
For key_2 through key_10, a descriptor address of 0, or a length of 0, or a 
string address of 0 terminates the list. 


Librarian (LBR) Routines 
LBR$GET_HELP 


The key argument may contain any of the following special character 
strings: 


String Meaning 


* 


Return all level 1 help text in the library. 


KEY... Return all help text associated with the specified key and its subkeys 
(valid for level 1 keys only). 


* 


Return all help text in the library. 





DESCRIPTION LBR$GET_HELP returns all help text in the same format as the output 
returned by the DCL command HELP; that is, it indents two spaces for 
every key level of text displayed. (Because of this formatting, you may 
want to make your help messages shorter than 80 characters, so they fit 
on one line on terminal screens with the width set to 80.) If you do not 
want the help text indented to the appropriate help level, you must supply 
your own routine to change the format. 


Note that most application programs use LBR$OUTPUT_HELP instead of 
LBR$GET_HELP. 





CONDITION Pr . 
LBR$_ILLCTL Specified library control index not valid. 

VALUES ee 

RETURNED LBR$_LIBNOTOPN Specified library not open. 
LBR$_NOTHLPLIB Specified library not a help library. 
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LBR$GET_HISTORY Retrieve a Library Update 


History Record 


The LBR$GET_HISTORY routine returns each library update history record to 
a user-specified action routine. 





FORMAT 


LBR$GET_HISTORY /ibrary_index ,action_routine 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
eh a argument is the address of the longword that contains the 
index. 


action_routine 

VMS usage: procedure 

type: procedure entry mask 

access: modify 

mechanism: by reference 

User-supplied routine for processing library update history records. The 
action_routine argument is the address of the entry mask of this user- 
supplied routine. The routine is invoked once for each update history 
record in the library. One argument is passed to the routine, namely, the 
address of a descriptor pointing to a history record. 





DESCRIPTION 
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This routine retrieves the library update history records written by the 
routine LBR$PUT_HISTORY. 


Librarian (LBR) Routines 
LBR$GET_HISTORY 





CONDITION 
LBR$_NORMAL Normal exit from the routine. 
VALUES a ; 
LBR$_EMPTYHIST History empty. This is an informational code, not an 
RETURNED error code. 
LBR$_NOHISTORY No update history. This is an informational code, not 
an error code. 
LBR$_INTRNLERR Internal librarian routine error occurred. 
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LBRS$GET_ INDEX Call a Routine for Selected Index 


Keys 


The LBR$GET_INDEX routine calls a user-supplied routine for selected keys 
in an index. 





FORMAT 


LBR$GET_INDEX /ibrary_index ,index_number 
,routine_name [,match_desc] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


index_number 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Number of the library index. The index_number argument is the address 
of a longword containing the index number. This is the index number 
associated with the keys you want to use as input to the user-supplied 
routine (see Section 8.1.2.3). 


routine_name 

VMS usage: procedure 

type: procedure entry mask 

access: read only 

mechanism: by reference 

User-supplied routine called for each of the specified index keys. The 
routine_name argument is the address of the entry mask for this user- 
supplied routine. 
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LBR$GET_INDEX passes two arguments to the routine: 
e A key name. 


— For libraries with ASCII keys, the key_name argument is the 
address of a string descriptor pointing to the key. Note that the 
string and the string descriptor passed to the routine are valid only 
for the duration of that call. The string must be privately copied if 
you need it again for more processing. 


— For libraries with binary keys, the key_name argument is the 
address of an unsigned longword containing the key number. 


e The record’s file address (RFA) of the module’s header for this key 
name. The RFA argument is the address of a 2-longword array that 
contains the RFA. 


The routine must return a value to indicate success or failure. If the 
routine returns a false value (low bit = 0), LBR$GET_INDEX stops 
searching the index and returns the status value of the user-specified 
routine to the calling program. 


The routine cannot contain calls to either LBR$DELETE_KEY or 
LBR$SINSERT_KEY. 


match_desc 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Key matching identifier. The match_desc argument is the address of a 
string descriptor pointing to a string used to identify which keys result in 
calls to the user-supplied routine. Wildcard characters are allowed in this 
string. If you omit this argument, the routine is called for every key in 


the index. The match_desce argument is valid only for libraries that have 
ASCII keys. 





DESCRIPTION 


LBR$GET_INDEX searches through the specified index for a key that 
matches the argument match_desc. Each time it finds a match, it calls 
the routine specified by the routine_name argument. If you do not 
specify the match_desc argument, it calls the routine for every key in the 
index. 


For example, if you call LBR$GET_INDEX with match_desc equal to TR* 
and index_number set to 1 (module name table), then LBR$GET_INDEX 
calls routine_name for each module whose name begins with TR. 





CONDITION 
VALUES 
RETURNED 


LBR$_ILLCTL Specified library control index not valid. 
LBR$_ILLIDXNUM Specified index number not valid. 
LBR$_LIBNOTOPN Specified library not open. 
LBR$_NULIDX Specified library empty. . 
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LBR$GET_RECORD Read a Data Record 


The LBR$GET_RECORD routine returns the next data record in the module 
associated with a specified key. 











FORMAT LBR$GET_RECORD _library_index [,inbufdes] 
[,outbufdes] 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENTS __ /ibrary_index 
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VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. The library must be open and LBR$LOOKUP_KEY or LBR$FIND 
must have been called to find the key associated with the module whose 
records you want to read. 


inbufdes 

VMS usage: char_string 

type: character string 

access: write only 

mechanism: by descriptor 

User buffer to receive the record. The inbufdes argument is the address 
of a string descriptor that points to the buffer that receives the record 
from LBR$GET_RECORD. This argument is required when the librarian 
subroutine record access is set to move mode (which is the default). This 
argument is not used if the record access mode is set to locate mode. The 
DESCRIPTION section contains more information about the locate and 
move modes. 


outbufdes 

VMS usage: char_string 

type: character string 

access: write only 

mechanism: by descriptor 

String descriptor that receives the actual length and address of the data 
for the record returned. The outbufdes argument is the address of the 
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string descriptor for the returned record. The length and address fields 
of the string descriptor are filled in by the LBR$GET_RECORD routine. 
This parameter must be specified when Librarian subroutine record access 
is set to locate mode. This parameter is optional if record access mode is 
set to move mode. The DESCRIPTION section contains more information 
about the locate and move modes. 





DESCRIPTION 


Before calling LBR$GET_RECORD, you must first call LBR$LOOKUP_ 
KEY or LBR$FIND to set the internal library read context to the record’s 
file address (RFA) of the module header of the module whose records you 
want to read. 


LBR$GET_RECORD uses two record access modes: locate mode and 
move mode. Move mode is the default. The LBR$SET_LOCATE and 
LBR$SET_MOVE subroutines set these modes. The record access modes 
are mutually exclusive; that is, when one is set the other is turned off. 
If move mode is set, LBR$GET_RECORD copies the record to the user- 
specified buffer described by inbufdes. If you have optionally specified the 
output buffer string descriptor, outbufdes, the librarian fills it with the 
actual length and address of the data. If locate mode is set, LBR$GET_ 
RECORD returns the record by way of an ‘internal subroutine buffer, 
pointing the outbufdes descriptor to the internal buffer. The second 
parameter, inbufdes, is not used when locate mode is set. 





CONDITION 
VALUES 
RETURNED 


LBR$_ILLCTL Specified library control index not valid. 
LBR$_LIBNOTOPN Specified library not open. 

LBR$_LKPNOTDON Requested key lookup not done. 

RMS$_EOF Error. An attempt has been made to read past the 


logical end of the data in the module. 


LBR-39 


Librarian (LBR) Routines 
LBRSINI_CONTROL 


LBRS$INI_CONTROL Initialize a Library Control 


Structure 


The LBR$INI_CONTROL routine initializes a control structure, called a library 
control index, to identify the library for use by other Librarian routines. 





FORMAT 


LBRS$INILCONTROL /ibrary_index ,func [,type] 
[,namblk] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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library_index 
VMS usage: longword_unsigned 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of a longword that is to receive 

the index. 


func | 
VMS usage: longword_unsigned | 
type: longword (unsigned) 

access: read only 


mechanism: by reference 

Library function to be performed. The func argument is the address 

of the longword that contains the library function. Valid functions are 
LBR$C_CREATE, LBR$C_READ, and LBR$C_UPDATE. (These symbols 
are defined by the $LBRDEF macro in SYS$LIBRARY:STARLET.MLB.) 


type 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Library type. The type argument is the address of the longword 

containing the library type. Valid library types are LBR$C_TYP_OBJ 

(object or shareable image), LBR$C_TYP_MLB (macro), LBR$C_TYP_ / 
HLP (help), LBR$C_TYP_TXT (text), LBR$C_TYP_UNK (unknown), or, 
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for user-developed libraries, a type in the range of LBR$¢C_TYP_USRLW 
through LBR$C_TYP_USRHI. 


namblk 

VMS usage: nam 

type: longword (unsigned) 
access: read only 


mechanism: by reference 

VMS RMS name block (NAM). The namblk argument is the address of 
a variable-length data structure containing an RMS NAM block. The 
LBR$OPEN routine fills in the information in the NAM block so that 

it can be used later to open the library. If the NAM block has this file 
identification in it from previous use, the LBR$OPEN routine uses the 
VMS RMS open-by-NAM block option. This argument is optional and 
should be used if the library will be opened many times during a single 
run of the program. For a detailed description of VMS RMS NAM blocks, 
see the VMS Record Management Services Manual. 





DESCRIPTION 


Except for the LBR$0UTPUT_HELP routine, you must call LBR$INI_ 
CONTROL before calling any other librarian routine. After you initialize 
the library control index, you must open the library or create a new one © 
using the LBR$OPEN routine. You can then call other librarian routines 
that you need. After you finish working with a library, close it with the 
LBR$CLOSE routine. 


LBR$INI_CONTROL initializes a library by filling the longword referenced 
by the library_index argument with the control index of the library. 
Upon completion of the call, the index can be used to refer to the current 
library in all future routine calls. Therefore, your program must not alter 
this value. 


You can have up to 16 libraries open simultaneously in your program. 





CONDITION 
VALUES 
RETURNED 


LBR$_NORMAL Library control index initialized successfully. 
LBR$_ILLFUNC Requested function not valid. 

LBR$_ILLTYP Specified library type not valid. 

LBR$_TOOMNYLIB Error. An attempt was made to allocate more than 16 


control indexes. 
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LBR$INSERT_KEY Insert a New Key 


The LBR$INSERT_KEY routine inserts a new key in the current library index. 











FORMAT LBRSINSERT_KEY _/ibrary_index ,key_name , txtrfa 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write oniy 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS __ /ibrary_index 
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VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


key_name 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 

Name of the new key you are inserting. 


If the library uses binary keys, the key_name argument is the address of 
an unsigned longword containing the value of the key. 


If the library uses ASCII keys, the key_name argument is the address of 
a string descriptor of the key with the following argument characteristics. 


Argument 

Characteristics Entry 

VMS Usage Char_string 
Type Character string 
Access Read only 
Mechanism By descriptor 
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txtrfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: modify 


mechanism: by reference 

Record file address (RFA) of the module associated with the new key you 
are inserting. The txtrfa argument is the address of a 2-longword array 
containing the RFA. You can use the RFA returned by the first call to 
LBR$PUT_RECORD. 





DESCRIPTION You cannot call LBR$INSERT_KEY within the user-supplied routine 


specified in LBR$SEARCH or LBR$GET_INDEX. 





CONDITION 
VALUES 
RETURNED 


LBR$_ILLCTL Specified library control index not valid. 

LBR$_INVRFA Specified RFA does not point to valid data. 

LBR$_DUPKEY Index already contains the specified key. 

LBR$_LIBNOTOPN Specified library not open. 

LBR$_UPDURTRAV LBR$SINSERT_KEY was called by the user-defined 
routine specified in LBRSSEARCH or LBR$GET_ 
INDEX. 
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LBR$LOOKUP_KEY Look Up a Library Key 


The LBR$LOOKUP_KEY routine looks up a key in the library’s current index 
and prepares to access the data in the module associated with the key. 











FORMAT LBR$SLOOKUP_KEY _/ibrary_index ,key_name , txtrfa 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS __ /ibrary_index 
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VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_LCONTROL routine. The 
eu a aaa argument is the address of the longword that contains the 
index. 


key_name 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Name of the library key. If the library uses binary keys, the key_name 
argument is the address of the unsigned longword value of the key. 


If the library uses ASCII keys, the key_name argument is the address of 
a string descriptor for the key with the following argument characteristics. 


Argument Characteristics Entry 

VMS Usage Char_string 
Type Character string 
Access Read only 
Mechanism By descriptor 
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txirfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 

The record’s file address (RFA) of the library module header. The txtrfa 
argument is the address of the 2-longword array that receives the RFA of 
the module header. 





DESCRIPTION 


If LBR$LOOKUP_KEY finds the specified key, it initializes internal tables 
so that you can access the associated data. 


This routine returns the RFA (consisting of the virtual block number 
(VBN) and the byte offset) to the 2-longword array referenced by txtrfa. 
Note that the RFA is only 6 bytes long. 





CONDITION 
VALUES 
RETURNED 


LBR$_ILLCTL Specified library control index not valid. 
LBR$_INVRFA RFA obtained not valid. 
LBR$_KEYNOTFND Specified key not found. 
LBR$_LIBNOTOPN Specified library not open. 
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LBRS$OPEN Open or Create a Library 


The LBR$OPEN routine opens an existing library or creates a new one. 





FORMAT 


LBRS$OPEN /ibrary_index [,fns] [,create_options] [,dns] 
[rlfna] [,rns] [,rnslen] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of a longword containing the 
index. 


fns 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 

File specification of the library. The fns argument is the address of a 
string descriptor pointing to the file specification. Unless the VMS RMS 
NAM block address was previously supplied in the LBR$INIL-CONTROL 
routine and contained a file specification, this argument must be included. 
Otherwise, the librarian returns an error (LBR$_NOFILNAM). 


create_options 

VMS usage: vector_longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library characteristics. The create_options argument is the address 
of an array of 20 longwords that define the characteristics of the library 
you are creating. If you are creating a library with LBR$C_CREATE, you 
must include the create-options argument. The following table shows 
the entries that the array must contain (the $LBRDEF and $CREDEF 
macros in SYS$LIBRARY:STARLET.MLB define the symbols listed). 


Offset in 
Longwords 


0 


9-20 
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Symbolic Name 


CRE$L_TYPE 
LBR$C_TYP_UNK (0) 
LBR$C_TYP_OBJ (1) 
LBR$C_TYP_MLB (2) 
LBR$C_TYP_HLP (3) 
LBR$C_TYP_TXT (4) 
(5-127) 

LBR$C_TYP_USR (128-255) 
CRE$L_KEYLEN 


CRE$L_ALLOC 
CRE$L_IDXMAX 
CRE$L_UHDMAX 
CRE$L_ENTALL 
CRE$L_LUHMAX 
CRE$L_VERTYP 
CRE$C_VMSV2 
CRE$C_VMSV3 


CRE$L_IDXOPT 
CRE$C_HLPCASING 


CRE$C_OBJCASING 


CRE$C_MACTXTCAS 


LBRSOPEN 
Contents 
Library type: 
Unknown/unspecified 


Object and/or shareable image 
Macro 

Help 

Text 

Reserved by Digital 
User-defined 


Maximum length of ASCII keys 
or, if 0, indicates 32-bit unsigned 
keys (binary keys) 


Initial library file allocation 


Number of library indexes 
(maximum of 8) 


Number of additional bytes to 
reserve in module header 


Number of index entries to 
preallocate 


Maximum number of library 
update history records to 
maintain 


Format of library to create: 
VMS Version 2.0 

VMS Version 3.0 

Index key casing option: 


Treat character case as it is for 
help libraries 


Treat character case as it is for 
object libraries 


Treat character case as it is for 
macro and text libraries 


Reserved by Digital 


The input of uppercase and lowercase characters is treated differently for 
help, object, macro, and text libraries. For details, see the VMS Librarian 
Utility Manual. 


dns 

VMS usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 

by descriptor 


Default file specification. The dns argument is the address of the string 
descriptor that points to the default file specification. See the VMS Record 
Management Services Manual for details about how defaults are processed. 
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LBRSOPEN 
rifna 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Related file name. The rlfna argument is the address of a VMS RMS 
NAM block pointing to the related file name. If you do not specify rlfna, 
no related file name processing occurs. If a related file name is specified, 
only the file name, type, and version fields of the NAM block are used 
for related name block processing. The device and directory fields are not 
used. See the VMS Record Management Services Manual for details on 
processing related file names. 
rns 
VMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 
Resultant file specification returned. The rns argument is the address 
of a string descriptor pointing to a buffer that is to receive the resultant 
file specification string. If an error occurs during an attempt to open the 
library, the expanded name string is returned instead. 
rnslen 
VMS usage: longword_signed 
type: longword (signed) 
access: write only 
mechanism: by reference 
Length of the resultant or expanded file name. The rnslen argument 
is the address of a longword receiving the length of the resultant file 
specification string (or the length of the expanded name string if there was 
an error in opening the library). 

DESCRIPTION You can call this routine only after you call LBR$INI_LCONTROL and 
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before you call any other librarian routine except LBR$O0UTPUT_HELP. 


When the library is successfully opened, the librarian routine reads the 
library header into memory and sets the default index to 1. 


If the library cannot be opened because it is already open for a write 
operation, LBR$OPEN retries the open operation every second for a 
maximum of 30 seconds before returning the VMS RMS error, RMS$_FLK, 
to the caller. 
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CONDITION 
VALUES 
RETURNED 


LBR$_OLDLIBRARY 


LBR$_ERRCLOSE 


LBR$_ILLCREOPT 
LBR$_ILLCTL 
LBR$_ILLFMT 
LBR$_ILLFUNC 
LBR$_LIBOPN 
LBR$_NOFILNAM 


LBR$_OLDMISMCH 


LBR$_TYPMISMCH 


Success. The specified library has been opened; the 
library was created with an old library format. 


Error. When the library was last modified while 
opened for write access, the write operation was 
interrupted. This left the library in an inconsistent 
state. 


Requested create options not valid or not supplied. 
Specified library control index not valid. 

Specified library format not valid. 

Specified library function not valid. 

Specified library already open. 


Error. The fns argument was not supplied or the VAX 
RMS NAM block was not filled in. 


Requested library function conflicts with old library 
type specified. 


Library type does not match the requested type. 
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LBRSOUTPUT_HELP Output Help Messages 


The LBR$OUTPUT_HELP routine outputs help text to a user-supplied 
output routine. The text is obtained from an explicitly named help library 

or, optionally, from user-specified default help libraries. An optional prompting 
mode is available that enables LBR$OUTPUT_HELP to interact with you and 
continue to provide help information after the initial help request has been 
Satisfied. 








FORMAT LBRSOUTPUT_HELP output_routine [output_ width] 
[line_desc] [,library_name] 
[flags] [,input_routine] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _ output_routine 
VMS usage: procedure 
type: procedure entry mask 
access: write only 
mechanism: by reference 
Name of a routine that writes help text a line at a time. The output_ 
routine argument is the address of the entry mask of the routine to call. 
You should specify either the address of LIB$PUT_OUTPUT or a routine 
of your own that has the same calling format as LIB${PUT_OUTPUT. 


output_width 

VMS usage: longword_signed 

type: longword (signed) 

access: read only 

mechanism: by reference 

Width of the help-text line to be passed to the user-supplied output 
routine. The output_width argument is the address of a longword 
containing the width of the text line to be passed to the user-supplied 
output routine. If you omit output_width or specify it as 0, the default 
output width is 80 characters per line. 
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line_desc 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Contents of the help request line. The line_dese argument is the address 
of a string descriptor pointing to a character string containing one or more 
help keys defining the help requested, for example, the HELP command 
line minus the HELP command and HELP command qualifiers. The 
default is a string descriptor for an empty string. 


library_name 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Name of the main library. The library_name argument is the address 
of a string descriptor pointing to the main library file specification string. 
The default is a null string, which means you should use the default help 
libraries. If you omit the device and directory specifications, the default is 
SYS$HELP. The default file type is HLB. 


flags 

VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 
Flags specifying help output options. The flags argument is the address of 
an unsigned longword that contains the following flags. 


Flag Description 


HLP$M_PROMPT When set, interactive help prompting is in effect. 


HLP$M_PROCESS When set, the process logical name table is searched for 
default help libraries. 

HLP$M_GROUP When set, the group logical name table is searched for group 
default help libraries. 

HLP$M_SYSTEM When set, the system logical name table is searched for 
system default help libraries. 

HLP$M_LIBLIST When set, the list of default libraries available is output with the 
list of topics available. 


HLP$M_HELP When set, the list of topics available in a help library is 
preceded by the major portion of the text on HELP. 


(The $HLPDEF macro in SYS$LIBRARY:STARLET.MLB defines these flag 
symbols.) 


If you omit this longword, the default is for prompting and all default 
library searching to be enabled, but no library list will be generated and 
no help text will precede the list of topics. 


LBR-51 


Librarian (LBR) Routines 
LBRSOUTPUT_HELP 


input_routine 

VMS usage: procedure 

type: procedure entry mask 

access: read only 

mechanism: by reference 

Routine used for prompting. The input_routine argument is the address 
of the entry mask of the prompting routine. You should specify either the 
address of LIB$GET_INPUT or a routine of your own that has the same 
calling format as LIB$GET_INPUT. This argument must be supplied when 
the HELP command is run in prompting mode (that is, HLP$M_PROMPT 
is set or defaulted). 





DESCRIPTION 
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The LBR$OUTPUT_HELP routine provides a simple, one-call method to 
initiate an interactive help session. Help library bookkeeping functions, 
such as LBR$INI_CONTROL and LBR$OPEN, are handled internally. 
You should not call LBR$INI_CONTROL or LBR$OPEN before you issue a 
call to LBR$OUTPUT_HELP. 


LBR$OUTPUT_HELP accepts help keys in the same format as LBR$GET_ 
HELP, with the following qualifications: 


¢ Ifthe keyword HELP is supplied, help text on HELP is output, 
followed by a list of HELP subtopics available. 


If no help keys are provided or if the line_dese argument is 0, a list of 
topics available in the root library is output. 


¢ Ifthe line_dese argument contains a list of help keys, then each key 
must be separated from its predecessor by a slash (/) or by one or 
more spaces. 


¢ The first key can specify a library to replace the main library as the 
root library (the first library searched) in which LBRS{OUTPUT_HELP 
searches for help. A key used for this purpose must have the form 
<@filespec>, where filespec is subject to the same restrictions as the 
library_name argument. If the specified library is an enabled user- 
defined default library, then filespec can be abbreviated as any unique 
substring of that default library’s logical name translation. 


In default library searches, you can define one or more default libraries 
for LBR$0UTPUT_HELP to search for help information not contained in 
the root library. You do this by equating logical names (HLP$LIBRARY, 
HLP$LIBRARY_1, ... ,HLP$LIBRARY_999) to the file specifications 

of the default help libraries. You can define these logical names in the 
process, group, or system logical name table. 


If default library searching is enabled by the flags argument, 
LBR$OUTPUT_HELP uses those flags to determine which logical name 
tables are enabled and then automatically searches any user default 
libraries that have been defined in those logical name tables. The library 
search order proceeds as follows: root library, main library (if specified 
and different from the root library), process libraries (if enabled), group 
libraries (if enabled), system libraries (if enabled). If the requested help 
information is not found in any of these libraries, LBR$O0UTPUT_HELP 
returns to the root library and issues a “help not found” message. 
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To enter an interactive help session (after your initial request for help 
has been satisfied), you must set the HLP$M_PROMPT bit in the flags 


argument. 

You can encounter four different types of prompt in an interactive help 
session. Each type represents a different level in the hierarchy of help 
available to you: 


1 Ifthe root library is the main library and you are not currently 
examining HELP for a particular topic, the prompt Topic? is output. 


2. If the root library is a library other than the main library and if you 
are not currently examining HELP for a particular topic, a prompt of 
the form @<library-spec>Topic? is output. 


3 If you are currently examining HELP for a particular topic (and 
subtopics), a prompt of the form <keyword...>subtopic? is output. 


4 A combination of 2 and 3. 


When you encounter one of these prompt messages, you can respond 
in any one of several ways. Each type of response and its effect on 
LBR$OUTPUT_HELP in each prompting situation is described in the 
following table. 


Response Action in the Current Prompt Environment! 


keyword[... ] (1,2) Search all enabled libraries for these keys. 


(3,4) Search additional help for the current topic (and 
subtopic) for these keys. 


@filespec [keyword[ .. . ]] (1,2) Same as above, except that the root library is 
the library specified by filespec. \f the specified library 
does not exist, treat @filespec as a normal key. 


(3,4) Same as above; treat @filespec as a normal 
key. 


? (1,2) Display a list of topics available in the root 
library. 


(3,4) Display a list of subtopics of the current topic 
(and subtopics) for which help exists. 


Carriage Return (1) Exit from LBRSOUTPUT_HELP. 
(2) Change root library to main library. 


(3,4) Strip the last keyword from a list of keys defining 
the current topic (and subtopic) environment. 
CTRL/Z — (1,2,3,4) Exit from LBRSOUTPUT_HELP. 


'Keyed to the prompt in the preceding list. 
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CONDITION a re . 
LBR$_ILLINROU Input routine improperly specified or omitted. 

VALUES oy v 

RETURNED LBR$_ILLOUTROU Output routine improperly specified or omitted. 
LBR$_NOHLPLIS Error. No default help libraries can be opened. 
LBR$_TOOMNYARG Error. Too many arguments were specified. 
LBR$_USRINPERR Error. An error status was returned by the user- 


supplied input routine. 
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LBR$PUT_END Write an End-of-Module Record 


The LBR$PUT_END routine marks the end of a sequence of records written 
to a library by the LBR$PUT_RECORD routine. 








FORMAT LBR$PUT_END /ibrary_index 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT library_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Library control index returned by the LBR$INI_LCONTROL routine. The 
library_index argument is the address of a longword containing the 
index. 





DESCRIPTION Call LBR$PUT_END after you write data records to the library with the 
LBR$PUT_RECORD routine. LBR$PUT_END terminates a module by 
attaching a 3-byte logical end-of-file record (hexadecimal 77,00,77) to the 





data. 
CONDITION LBR$_ILLCTL Specified lib ontrol index not valid 
ecified library control | not valid. 
VALUES LBR$_LIBNOTOPN eerie sia not open 
RETURNED | 
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LBR$PUT_ HISTORY Write an Update History 
Record 


The LBR$PUT_HISTORY routine adds an update history record to the end of 
the update history list. 











FORMAT LBR$PUT_HISTORY  /ibrary_index ,record_desc 
RETURNS VMS usage: cond_value - 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ /ibrary_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


record_desc 

VMS usage: char_string © 

type: character string 

access: read only 

mechanism: by descriptor 

Library history record. The record_dese argument is the address of a 
string descriptor pointing to the record to be added to the library update 
history. 





DESCRIPTION i LBR$PUT_HISTORY writes a new update history record. If the library 
already contains the maximum number of history records (as specified at 
creation time by CRE$L_LUHMAX, see LBR$OPEN for details), the oldest 
history record is deleted before the new record is added. 
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CONDITION 
V ALUES LBR$_NORMAL Normal exit from the routine. 
LBR$_NOHISTORY No update history. This is an informational code, not 
RETURNED an error code. 
LBR$_INTRNLERR Internal librarian error. 
LBR$_RECLNG Record length greater than that specified by LBR$C_ 
MAXRECSIZ. The record was not inserted or 
truncated. 
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LBR$PUT RECORD Write a Data Record 


The LBR$PUT_RECORD routine writes a data record beginning at the next 
free location in the library. 











FORMAT LBR$PUT_RECORD library_index ,bufdes , ixtrfa 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS _ /ibrary_index 
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VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


bufdes 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 
Record to be written to the library. The bufdes argument is the address 
of a string descriptor pointing to the buffer containing the output record. 


txtrfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 

Record’s file address (RFA) of the module header. The txtrfa argument is 
the address of a 2-longword array receiving the RFA of the newly created 
module header upon the first call to LBR$PUT_RECORD. 
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DESCRIPTION _eiIf this is the first call to LBR$PUT_RECORD, this routine first writes a 
module header and returns its RFA to the 2-longword array pointed to by 
txtrfa. LBR$PUT_RECORD then writes the supplied data record to the 
library. On subsequent calls to LBR$PUT_RECORD, this routine writes 
the data record beginning at the next free location in the library (after the 
previous record). The last record written for the module should be followed 
by a call to LBR$PUT_END. 





CONDITION LBR$_ILLCTL Specified library control index not valid 
VALUES LBR$_LIBNOTOPN ase fee not open. | 
RETURNED 
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LBRS$REPLACE KEY Replace a Library Key 


The LBR$REPLACE_KEY routine inserts a key in an index by changing the 
pointer associated with an existing key or by inserting a new key. 














FORMAT LBR$REPLACE_KEY /ibrary_index ,key_name ,oldrfa 
,newrta 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENTS __ /ibrary_index 
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VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
a aa argument is the address of the longword that contains the 
index. 


key_name 

VMS usage: char_string 

type: character string 

access: read only | 

mechanism: by descriptor 

Library key (for libraries with ASCII keys). The key_name argument is 
the address of a string descriptor for the key. 


key_name 


VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library key (for libraries with binary keys). The key_name argument is 
the address of an unsigned longword value for the key. 


oldrfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 
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Old RFA. The oldrfa argument is the address of a 2-longword array 
containing the original RFA (returned by LBR$LOOKUP_KEY) of the 
module header associated with the key you are replacing. 


newrfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

New RFA. The newrfa argument is the address of a 2-longword array 
containing the RFA (returned by LBR$PUT_RECORD) of the module 
header associated with the new key. 





DESCRIPTION _ If LBR$REPLACE_KEY does not find the key in the current index, it calls 
the LBR$INSERT_KEY routine to insert the key. If LBR$REPLACE_KEY 
does find the key, it modifies the key entry in the index so that it points to 
the new module header. 





CONDITION a . 
LBR$_ILLCTL Specified library control index not valid. 

VALUES ae 

RETURNED LBR$_LIBNOTOPN Specified library not open. 
LBR$_INVRFA Specified RFA not valid. 
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LBR$RET_ RMSSTV Return VMS RMS Status Value 


The LBR$RET_RMSSTV routine returns the status value of the last VMS 
Record Management Services (RMS) function performed by any librarian 








subroutine. 
FORMAT LBRS$RET_RMSSTV 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS — None. 





DESCRIPTION The LBR$RET_RMSSTV routine returns, as the status value, the status of 
the last RMS operation performed by the librarian. RMS status codes are 
defined by the $RMSDEF macro in SYS$LIBRARY:STARLET:MLB. 





CONDITION This routine returns any condition values returned by VMS RMS routines. 


VALUES 
RETURNED 
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LBR$SEARCH Search an Index 


The LBR$SEARCH routine finds index keys that point to specified data. 





FORMAT 


LBR$SEARCH /ibrary_index ,index_number 
,fa_to_find ,routine_name 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_ CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


index_number 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library index number. The index_number argument is the address of 


a longword containing the number of the index you want to search (see 
Section 8.1.2.3). 


tfa_to_find 

VMS usage: vector_longword_unsigned 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Record’s file address (RFA) of the module whose keys you are searching for. 
The rfa_to_find argument is the address of a 2-longword array containing 
the RFA (returned earlier by LBR$LOOKUP_KEY or LBR$PUT_ 
RECORD) of the module header. 
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LBRS$SEARCH 


routine_name 


VMS usage: procedure 

type: procedure entry mask 

access: read only 

mechanism: by reference 

Name of a user-supplied routine to process the keys. The routine_name 
argument is the address of the entry mask of a user-supplied routine to 
call for each key entry containing the RFA (in other words, for each key 
that points to the same module header). 


This user-supplied routine cannot contain any calls to LBR$DELETE_KEY 
or LBR$INSERT_KEY. 





DESCRIPTION 


Use LBR$SEARCH to find index keys that point to the same module 
header. Generally, in index number 1 (the module name table), just one 
key points to any particular module; thus, you would probably use this 
routine only to search library indexes where more than one key points to a 
module. For example, you might call LBR$SEARCH to find all the global 
symbols associated with an object module in an object library. 


If LBR$SEARCH finds an index key associated with the specified RFA, it 
calls a user-supplied routine with two arguments: 


e The key argument, which is the address of either of the following: 


- A string descriptor for the keyname (libraries with ASCII 
keynames). 


— An unsigned longword for the key value (libraries with binary 
keys). 


¢ The RFA argument, which is the address of a 2-longword array 
containing the RFA of the module header. 


The routine must return a value to indicate success or failure. If the 
specified routine returns a false value (low bit = 0), then the index search 
terminates. 


Note that the key found by LBR$SEARCH is valid only during the call to 
the user-supplied routine. If you want to use the key later, you must copy 
it. 





CONDITION 
VALUES 
RETURNED 
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LBR$_ILLCTL Specified library control index not valid. 
LBR$_ILLIDXNUM Specified library index number not valid. 
LBR$_KEYNOTFND Librarian did not find any keys with the specified RFA. 
LBR$_LIBNOTOPN Specified library not open. 
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LBR$SET_INDEX Set the Current Index Number 


The LBR$SET_INDEX routine sets the index number to use when processing 
libraries that have more than one index. 





FORMAT 


LBRS$SET_INDEX §/ibrary_index ,index_number 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


library_index 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 


index_number 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Index number you want to establish as the current index number. The 
library_index is the address of the longword that contains the number of 
the index you want to establish as the current index. (See Section 8.1.2.3.) 





DESCRIPTION 


When you call LBR$INI_CONTROL, the librarian sets the current library 
index to 1 (the module name table, unless the library is a user-developed 
library). If you need to process another library index, you must use 
LBR$SET_INDEX to change the current library index. 


Note that macro, help, and text libraries contain only one index; therefore, 
you do not need to call LBR$SET_INDEX. Object libraries contain two 
indexes. If you want to access the global symbol table, you must call 

the LBR$SET_INDEX routine to set the index number. User-developed 
libraries can contain more than one index; therefore, you may need to call 
LBR$SET_INDEX to set the index number. 
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Upon successful completion, LBR$SET_INDEX sets the current library 
index to the requested index number. The librarian routines number 
indexes starting with 1. 





CONDITION a 
LBR$_ILLCTL Specified library control index not valid. 

VALUES oe i 

RETURNED LBR$_ILLIDXNUM Library index number specified not valid. 
LBR$_LIBNOTOPN Specified library not open. 
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LBR$SET_LOCATE Set Record Access to Locate 
Mode 


The LBR$SET_LOCATE routine sets the record access of librarian 
subroutines to locate mode. 








FORMAT LBR$SET_LOCATE /ibrary_index 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT library_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 
index. 





DESCRIPTION Librarian record access may be set to move mode (the default set by 
LBR$SET_MOVE) or locate mode. The setting affects the operation of the 
LBR$GET_RECORD routine. 


If move mode is set (the default), LBR$GET_RECORD copies the 
requested record to the specified user buffer. If locate mode is set, the 
record is not copied. Instead, the outbufdes descriptor is set to reference 
the internal librarian subroutine buffer that contains the record. 





CONDITION Lanes . . 
LBR¢_ILLCTL Specified library control index not valid. 

VALUES LBR$_LIBNOTOPN Specified library not open 

RETURNED ’ 
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LBR$SET MODULE Read or Update a Module 
Header 


The LBR$SET_MODULE routine reads, and optionally updates, the module 
header associated with a given record's file address (RFA). 








FORMAT LBRS$SET_MODULE /ibrary_index ,rfa [,bufdesc] 
[,buflen] [,updatedesc] 
RETURNS VMS usage: ‘cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 


ARGUMENTS __/ibrary_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Library control index returned by the LBR$INI_CONTROL routine. The 
library_index argument is the address of the longword that contains the 





index. 

rfa 

VMS usage: vector_longword_unsigned 
type: longword (unsigned). 
access: read only 


mechanism: by reference 

Record’s file address (RFA) associated with the module header. The 
rfa argument is the address of a 2-longword array containing the RFA 
returned by LBR$PUT_RECORD or LBR$LOOKUP_KEY. 


bufdesc 

VMS usage: char_string 

type: character string 

access: write only 

mechanism: by descriptor 

Buffer that receives the module header. The bufdesc argument is the 
address of a string descriptor pointing to the buffer that receives the 
module header. The buffer must be the size specified by the symbol 
MHD$B_USRDAT plus the value of the CRE$L_UHDMAX create option. 
The MHD$ and CRE$ symbols are defined in the modules $MHDDEF and 
$CREDEF, which are stored in SYS$LIBRARY:STARLET.MLB. 
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buflen 

_ VMS usage: longword_signed 
type: longword (signed) 
access: write only 


mechanism: by reference 
Length of the module header. The buflen argument is the address of a 
longword receiving the length of the returned module header. 


updatedesc 


VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Additional information to be stored with the module header. The 
updatedesc argument is the address of a string descriptor pointing to 
additional data that the librarian stores with the module header. If you 
include this argument, the librarian updates the module header with the 
additional information. 





DESCRIPTION 


If you specify bufdesc, the librarian routine returns the module header 
into the buffer. If you specify buflen, the librarian routine also returns 
the buffer’s length. If you specify updatedesc, the routine updates the 
header information. 


You define the maximum length of the update information (by specifying 
a value for CRE$L_UHDMAX) when you create the library. The librarian 
zero-fills the information if it is less than the maximum length or 
truncates it if it exceeds the maximum length. 





CONDITION 
VALUES 
RETURNED 


LBR$_HDRTRUNC Buffer supplied to hold the module header was too 
small. 

LBRS$ILLCTL Specified library control index not valid. 

LBR$_ILLOP Error. The updatedesc argument was supplied and 


the library was a Version 1.0 library or the library was 
opened only for read access. 


LBR$_INVRFA Specified RFA does not point to a valid module 
header. 
LBR$_LIBNOTOPN Specified library not open. 


LBR-69 


Librarian (LBR) Routines 
LBR$SET_MOVE 


LBR$SET MOVE Set Record Access to Move Mode 


The LBR$SET_MOVE routine sets the record access of Librarian subroutines 
to move mode. 








FORMAT LBR$SET_MOVE _/ibrary_index 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT library_index 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Library control index returned by the LBR$INI_LCONTROL routine. The 
ne ae ais argument is the address of the longword that contains the 
iInaex. 





DESCRIPTION _seLibrarian record access may be set to move mode (the default, set by 
LBR$SET_MOVE) or locate mode. The setting affects the operation of the 
LBR$GET_RECORD routine. If move mode is set, LBR$GET_RECORD 
copies the requested record to the specified user buffer. For details, see the 
description of LER$GET_RECORD. 





CONDITION she tes 
LBR$_ILLCTL Specified library control index not valid. 

VALUES LBR$_LIBNOTOPN Specified library not open 

RETURNED 7 
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Introduction to MAIL Routines 


Messages 


The callable interface of the VMS Mail Utility (MAIL) lets you send 
messages to users on your system or on any other VAX computer 
connected to your system with DECnet—VAX. This chapter describes 
how application programs using callable MAIL routines can perform the 
following functions: 


¢ Create and access mail files 
e Access and manipulate a message or group of messages 
¢ Create and send messages to a user or group of users 


e Access and manipulate the user common database 


For information about the DCL interface to the VMS Mail Utility, see the 
VMS Mail Utility Manual. 





Messages are files that contain information you want to send to other 
users. Short messages, smaller than 3 blocks, are part of a mail file, while 
long messages, larger than 3 blocks, are external sequential files. 


External files reside in the same directory as the mail file that points to 
them. 


Structure of a Message 


A message consists of header information and the bodypart. The 
message bodypart consists of text records that contain information you 
want to send to another user. 


Figure 9-1 illustrates the format of a mail message. 
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Figure 9-1 Standard Message Format 


From: MYNODE::USER "The Celestial Navigator" 1] 
To: NODE: :J_DOE 

cc: USER 3) 

Subj: Perseids ... 0 


Get ready. Tuesday of this week (August 12th), one 5 ] 

of the most abundant meteor showers of the year will occur. 

The Perseids, also known as the St. Laurence’s Tears, stream 
across earth’s orbit at 319.3 degrees. Radiant 3h4m +58 degrees. 
Fine for photography with an average magnitude of 2.27. 

There will be some fireballs, fainter white or yellow 


mat ~ a alok . LA te 
meteors, and brighter green or orange or red ones. About one 


third of the meteors, including all the brightest, leave 
yellowish trains, which may be spectacular, up to 2 
degrees wide and lasting up to 100 seconds. Brighter 
meteors often end in flares or bursts. 

The parts of a message are as follows: 

e Header information 


@ From: field specifies the sender and an optional personal name 
string 


@ To: field specifies the direct addressee. 

© CC: field specifies the carbon copy addressee. 

@ Subj: field specifies the topic of the message. 
¢ Bodypart 

© First line of the bodypart 

© Last line of the bodypart 


External Message Identification Number 


In addition, the file name of an external message uses the following 
format: 


MATLS$Snnnnnnnnnnnnnnnn. MAI 


where n ... n is the external message identification number. 





Folders 
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MAIL organizes messages by date and time received and, secondarily, 

by folder name. All messages are associated with a folder name—either 
default folders or user-specified folders. VMS MAIL associates mail 
messages with one of three default mail folder names. Table 9-1 describes 
the three default MAIL folders. 
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Table 9-1 Default Mail Folders 


Folder Contents 

NEWMAIL Newly received, unread messages 

MAIL Messages that have been read and not deleted 
WASTEBASKET Messages designated for deletion 


You can also place messages in any user-defined mail folder. 





9.4 Mail Files 


A mail file is an indexed sequential (ISAM) file that contains the following 
types of data: 


¢ Header information for all messages 
e Text of short messages 


e¢ Pointers to long messages 


In addition, you can select messages from mail files as well as copy or 
move messages to or from mail files. 


Mail File Format 


The indexed sequential mail file format offers two advantages: use of 
folders and faster access time than sequential access. ISAM mail files use 
two keys to locate messages—a primary key denoting the date and time 
received and a secondary key using the folder name. 





9.5 User Common Database 


VMS MAIL maintains an indexed sequential data file VMSMAIL_ 
PROFILE.DATA that serves as a system-wide database of user profile 
entries. A user profile entry is a record that contains data describing a 
user’s default processing characteristics and whose primary key is the 
username. Table 9-2 summarizes information contained in a user profile 
entry. 


Table 9-2 User Profile information 


Field Function 

Directory Default MAIL subdirectory 

Form Default print form 

Forwarding address Forwarding address 

Personal name string User-specified character string included in the 


message header 
Queue name Default print queue name 


(continued on next page) 
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Table 9-2 (Cont.) User Profile Information 


Field Function 

Flags 
Automatic purge Purging of the wastebasket folder on exiting 
CC: prompt Carbon copy prompt 
Copy self forward Copy to self when forwarding a message 
Copy self reply Copy to self when replying to a message 
Copy self send Copy to self when sending a message 


Both the callable and user interfaces of the VMS MAIL utility use the 


ys el ee ee me em meen nee lh mn nana en Ah ama ntaw + 
COMMON Gavapvase vO GELETMINE Gerais processing characteristics. 


9.6 MAIL Processing Contexts 
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VMS MAIL defines four discrete levels of processing, or contexts for 
manipulating mail files, messages, folders, and the user common database 
as shown in Table 9-3. 


Table 9~3 Levels of MAIL Processing 





Context Entity 

Mail file Mail files and folders 

Message Mail files, folders, and messages 
Send Messages 

User User common database 


Within each context, your application processes specific entities in certain 
ways using callable MAIL routines as described in the sections that follow. 


Initiating a MAIL Context 


You must explicitly begin and end each MAIL context. Each group of 
routines contains a pair of context-initiating and terminating routines. 


When you begin processing in any context, VMS MAIL performs the 
following functions: 


1 Allocates sufficient virtual memory to manage context information 


2 Initializes context variables and internal structures 


Terminating a MAIL Context 


Terminating a MAIL processing context deallocates virtual memory. 
You must explicitly terminate processing in any context by calling a 
context-terminating routine. 
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9.6.1 Callable MAIL Routines 


There are four types of callable MAIL routines, each corresponding to 
the context within which they execute. A prefix identifies each functional 
group—MAIL$MAILFILE_, MAIL$MESSAGE_, MAIL$SEND_, and 
MAIL$USER_. 


Table 9—4 lists MAIL routines according to context. 


Table 9-4 Callable MAIL Routines 


Context Routine 


Mail file MAIL$MAILFILE_BEGIN 
MAIL$MAILFILE_CLOSE 
MAIL$MAILFILE_COMPRESS 
MAIL$MAILFILE_END 
MAIL$MAILFILE_INFO_FILE 
MAIL$MAILFILE_MODIFY 
MAIL$MAILFILE_OPEN 
MAIL$MAILFILE_PURGE_WASTE 


Message MAIL$MESSAGE_BEGIN 
MAIL$MESSAGE_COPY 
MAILSMESSAGE_DELETE 
MAILSMESSAGE_END 
MAILSMESSAGE_GET 
MAIL$MESSAGE_INFO 
MAILSMESSAGE_MODIFY 
MAILSMESSAGE_SELECT 


Send MAIL$SEND_ABORT 
MAIL$SEND_ADD_ADDRESS 
MAIL$SEND_ADD_ATTRIBUTE 
MAIL$SEND_ADD_BODYPART 
MAIL$SEND_BEGIN 
MAIL$SEND_END 
MAIL$SEND_MESSAGE 

User MAIL$USER_BEGIN 
MAILSUSER_DELETE_INFO 
MAIL$USER_END 
MAILSUSER_GET_INFO 
MAIL$USER_SET_INFO 


9.6.2 Single and Multiple Threads 


Once you have successfully initiated MAIL processing in a context, you 
have created a thread. A thread is a series of calls to MAIL routines that 
uses the same context information. Applications can contain one or more 
threads. 


Single Threads 


For example, an application that begins mail file processing; opens, 
compresses, and closes a mail file; and ends mail file context processing 
executes a single thread of procedures that reference the same context 
variable names and pass the same context information. 
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Multiple Threads 


You can create up to 31 concurrent threads. Applications that contain 
more than one thread must maintain unique context variables for each 
thread in order to pass thread-specific context information. 


VMS MAIL returns the condition value MAIL$_NOMORECTX when your 
process attempts to exceed the maximum number of allowable threads. 





9.7 Programming Considerations 


The calling sequence for all MAIL routines consists of a status variable, 


an entry point name, and an argument list. All arguments within the 


argument list are required. All callable MAIL routines use the same 
arguments in their calling sequences as described in the following 
example: 


STATUS=MAILSMAILFILE BEGIN (CONTEXT, IN_ITEM LIST, OUT_ITEM_LIST) 


The variable status receives the condition value, and the argument 
context receives the context information. The arguments in_item_list 
and out_item_list are input and output item lists that contain one or 
more input or output item descriptors. 


9.7.1 Condition Handling 


At run time, a hardware- or software-related event can occur that 
determines whether or not the application executes successfully. VMS 
MAIL processes such an event, or condition in the following ways: 


e Signals the condition value 


¢ Returns the error code 


You can establish your own condition handler or allow the program to 
signal the default VAX Condition Handler Facility (CHF). 


Returning Condition Values 


You can disable signaling for any call by specifying the item code MAIL$_ 
NOSIGNAL as an item in the input item list. 


9.7.2 Item Lists and Item Descriptors 
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Your application passes data to callable MAIL routines and receives data 
from routines through data structures called item lists defined in your 
program. 
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9.7.2.1 Structure of an item Descriptor 
An input or output item list is a data structure that consists of one or 
more input or output item descriptors. 


The following table summarizes the characteristics of item lists: 


Item Descriptor Characteristics 

Input Each descriptor points to a buffer or file from which MAIL 
reads data. 

Output Each descriptor points to a buffer or file to which MAIL writes 
data. 


An item descriptor is a data structure consisting of three longwords as 
described in Figure 9-2. 


Figure 9-2 Item Descriptor 


31 


15 0 
Buffer Address 
Return Length Address 







ZK-1705-GE 
Item descriptor fields are described as follows: 
Field Function 
Item code Specifies an action the routine is to perform. 
Buffer length Specifies the length in bytes of an input or output 
buffer. 
Buffer address Specifies the address of the input or output buffer. 
Return length address Depends on the type of item code specified as 
summarized below. 
Item 
Code Use 


Input Not used; specify 0. 


Output Address of a longword that receives 
the length of the result. 


Note: You can specify item descriptors in any order within an item list. 
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Item Codes 


The item code defines an action that the routine is to perform. Input 
and output item codes are specified in input and output item descriptors, 
respectively. 


Boolean input and output item codes request an operation but do not pass 
data to the called routine. For example, the item code MAIL$_USER_ 
SET_CC_PROMPT sets the CC prompt flag enabling use of CC: field text. 


For a complete list of input and output item codes, see Tables 9-9 and 
9-10. 


9.7.2.2 Null Item Lists 


Both the input and output item list arguments in the MAIL routine calling 
sequence are required. However, there might be situations when you do 
not want to request an operation or no input or output item codes are 
listed for the routine. In such cases, you must pass the value O in the 
function call. 


9.7.2.3 Declaring Item Lists and Item Descriptors 


Depending on the programming language you are using, refer to the 
appropriate language reference manual for more information about 
declaring data structures and creating variables. 


9.7.2.4 Terminating an Item List 


9.7.3. Action Routines 


Terminate an item list with a null item descriptor. Assign the value 0 to 
each field in the item descriptor. 


Certain callable MAIL routines allow you to specify an action routine. 
An action routine transfers control to a user-written subroutine that 
performs specific tasks. 


9.7.3.1 Types of Action Routines 


The mail file, message, and send contexts permit the use of action routines 
for specific reasons. The following table summarizes the types of action 
routines and the contexts in which they are used: 





Context Routine Action Routine 
Mail file MAIL$MAILFILE_INFO_FILE Folder action 
Message MAIL$MESSAGE_COPY Mail file action 

Folder action 
Send MAIL$SEND_MESSAGE Success 


MAIL-8 


Error 


The preceding table summarizes typical uses of action routines. However, 
an action routine can perform any task you specify. See the Guide to 
Creating VMS Modular Procedures for more information about action 
routines. 
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Mail File and Folder Action Routine Calling Sequence 


The main portion of the application calls the action routine and passes 
values to it using parameters. The calling sequence of a mail file or folder 
action routine is as follows: 


entry-point-name(userdata, foldername) 


The argument userdata is the address of an optional longword that 
contains user-specified data, and the argument foldername is the address 
of a descriptor of the foldername. 


Send Action Routine Calling Sequence 
The calling sequence of a send action routine is as follows: 
entry-point-name(username, signal-array, userdata) 


The argument username is the address of a descriptor of the username 
to which the application successfully sent a message; signal-array is the 
address of a signal array containing the success message; userdata is the 
address of an optional longword that contains user-specified data. 





9.8 Mail File Context 


Mail file context processing involves accessing and manipulating one or 
more mail files. Table 9-5 summarizes each mail file routine and its 
function. 


Table 9-5 Mail File Routines 


Routine Description 

MAIL$MAILFILE_BEGIN Initiates mail file processing 
MAIL$MAILFILE_CLOSE Closes a mail file 
MAIL$SMAILFILE_COMPRESS Compresses a mail file 
MAIL$MAILFILE_END Terminates mail file processing 
MAIL$MAILFILE_INFO_FILE Obtains information about the mail file 
MAIL$MAILFILE_MODIFY Changes the wastebasket folder name 
MAIL$MAILFILE_OPEN Opens a mail file 


MAIL$MAILFILE_PURGE_WASTE Purges a mail file 


Initiating the Mail File Context 


Your application must call MAIL$MAILFILE_BEGIN to perform mail file 
context processing. 


When you call MAIL$MAILFILE_BEGIN successfully and begin 
processing in the mail file context, you have created a thread. You must 
specify the same context variable name in routine calls within the same 
thread. 
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Terminating the Mail File Context 


Terminate processing in the mail file context calling MAIL routines in the 
following order: 


1 Terminate message context processing (if applicable) using 
MAIL$MESSAGE_END. 


2 Close the currently open mail file using MAIL$MAILFILE_CLOSE. 
3 Terminate mail file context processing using MAIL$MAILFILE_END. 


9.8.1 Managing Mail Files 


Using mail files involves opening and closing MAIL default and 
user-created mail files, using MAIL default and alternate mail file 
specifications, and purging and compressing mail files. 


9.8.1.1 Opening and Closing Mail Files 


Before you perform any activities on existing messages, folders, and mail 
files, you must first open a mail file. Whenever you open a mail file, you 
must do so explicitly using MAIL$SMAILFILE_OPEN. You can open only 
one mail file per mail file thread. 


Note that each routine references the same context variable. An open mail 
file must be explicitly closed with a call to MAIL$MAILFILE_CLOSE. 


9.8.1.1.1 Using the Default Specification for Mail Files 


To open a mail file, MAIL must first locate it using either a default or a 
user-specified mail file specification. A mail file specification consists of 
the following components: disk and directory, file name, and file type. 


If you use the default file specification, VMS MAIL locates and opens the 
default mail file using the following information: 


Component Source 

User’s disk and directory Retrieved from the user authorization file (UAF) 
MAIL subdirectory Retrieved from the user profile entry 

Mail file name and type MAIL.MAI 


9.8.1.1.2 Specifying an Alternate Mail File Specification 


MAIL-10 


You can use the default specication for mail files or specify all or part of an 
alternate mail file specification. 
When to Specify an Alternate Mail File Specification 


The following mail file routines accept alternate mail file specifications 
when you use the item codes MAIL$_ MAILFILE_DEFAULT_NAME or 
MAIL$_MAILFILE_NAME or both: 


¢ MAIL$MAILFILE_COMPRESS 
¢ MAIL$MAILFILE_INFO_FILE 
e MAIL$MAILFILE_MODIFY 
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e MAIL$MAILFILE_OPEN 


How VMS MAIL Creates an Alternate Mail File Specification 


VMS MAIL constructs an alternate mail file specification by modifying 
the default specification for mail files with your program-supplied mail file 
specifications in the following order of importance: 


1 Program-supplied file specification (MAIL$_MAILFILE_NAME) 
e Program-supplied disk and directory 
e Program-supplied file name and type 


2 Program-supplied default file specification (MAIL$ MAILFILE_ 
DEFAULT_NAME) 


¢ Program-supplied disk and directory 
e Program-supplied file name and type 
3 Default specification 


If you are using MAIL$_MAILFILE_DEFAULT_NAME and you specify 
0 as the buffer size and address, VMS MAIL uses the current device and 
directory. 


The default specification for mail files applies unless overridden by your 
program-supplied mail file specifications. Mail file specifications defined 
with MAIL$_MAILFILE_NAME override those defined with MAIL$_ 
MAILFILE_DEFAULT_NAME. 


For example, an application can override the default specification 
$DISKO:[USERJMAIL.MAIL by defining an alternate device 

type $DISK99: using MAIL$ MAILFILE_NAME. The result is 
$DISK99:[USER]JMAIL.MAI. The application can further modify the 
specification by defining a different mail file MYMAILFILE.MATI using 
MAIL$_ MAILFILE_DEFAULT_NAME. The new mail file specification is 
$DISK99:[(USERJMYMAILFILE.MAI. 


9.8.1.2 Displaying Folder Names 
As the size of your mail files increases with messages and folders, you 
might want to display your folder names. A user-written folder action 
routine lets you do this. 


In the mail file context, MAIL$MAILFILE_INFO_FILE can be used to 
invoke a folder action routine that displays folder names in a mail file. 

If you specify the item code MAIL$_MAILFILE_FOLDER_ROUTINE, 
MAIL$MAILFILE_INFO passes a descriptor of a folder name to the action 
routine repeatedly until it encounters no more folder names and passes a 
null descriptor. 
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9.8.1.3 Purging Mail Files Using the Wastebasket Folder 


VMS MAIL associates messages designated for deletion with a 
wastebasket folder. Purging mail files of messages in the wastebasket 
folder that are designated for deletion is one way to conserve disk space. 
You can also use VMS MAIL to conserve disk space by reclaiming disk 
space and compressing mail files, as described in the sections that follow. 


Note that purging the wastebasket folder removes the messages from the 
wastebasket folder but might not reclaim disk space. 


9.8.1.3.1 Reclaiming Disk Space 


However, simply deleting the messages does not mean you will 
automatically reclaim the disk space. VMS MAIL uses a system-defined 
threshold of bytes designated for deletion to determine when to reclaim 
disk space. When the total number of total bytes designated for deletion 
exceeds the threshold, VMS MAIL performs a reclaim operation. 


You can override the deleted bytes threshold and request a reclaim 
operation using MAIL$MAILFILE_PURGE_WASTE with the input item 
code MAIL$_MAILFILE_RECLAIM. 


See the VMS Convert and Convert/Reclaim Utility Manual for more 
information. 


9.8.1.3.2 Compressing Mail Files 


Compressing mail files is a way of conserving disk space. Mail file 
compression provides faster access to the folders and messages within the 
mail file. When you call MAIL$MAILFILE_COMPRESS, MAIL removes 
unused space within the specified mail file. 





9.9 Message Context 
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Message context processing involves manipulating existing messages as 
well as creating and deleting folders and mail files. Table 9~6 summarizes 
routines used in the message context. 


Table 9-6 Message Routines 


Routine Description 
MAIL$MESSAGE_BEGIN Initiates message processing 
MAIL$MESSAGE_COPY Copies messages 
MAIL$MESSAGE_DELETE Deletes messages 
MAIL$MESSAGE_END Terminates message processing 
MAIL$MESSAGE_GET Retrieves a message 


(continued on next page) 
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Table 9-6 (Cont.) Message Routines 


Routine Description 


MAIL$MESSAGE_INFO Obtains information about a specified message 
MAIL$MESSAGE_MODIFY Identfies a message as replied, new, or marked 


MAIL$MESSAGE_SELECT Selects a message or messages from the currently 
open mail file 


Initiating the Message Context 


The message context is the only MAIL context that your application cannot 
invoke directly. Message context processing can begin only after a mail file 
has been opened. Your application must explicitly call MAILSMESSAGE_ 
BEGIN in order to execute message context processing. 


VMS MAIL passes mail file context information to the message context 
when you call MAILSMESSAGE_BEGIN with the input item code MAIL$_ 
MESSAGE_FILE_CTX. 


Terminating the Message Context 


To terminate message level processing for a specific thread, you must call 
MAIL$MESSAGE_END to deallocate memory. 


9.9.1 Selecting Messages 


Applications select messages using MAIL$MESSAGE_SELECT to copy 
and move messages between folders as well as to read, modify, or delete 
messages. You must select messages before you can use them. You must 
specify a folder name when you select messages. 


You can select messages based on the following criteria: matching 
character strings, message arrival date and time, and message 
characteristics. 


Matching Character Strings 


You can select a message or set of messages from a mail file by specifying 
one or more character substrings that you want to match with a character 
substring in the header information of a message or group of messages. 
You must specify the specific bodypart in the message header where the 
substring is located. 


e From: line 

¢ To: line 

¢ CC: line 

e Subject: line 

VMS MAIL searches the specified folder for message headers that contain 
the matching character substring. This method of selection is useful when 


you want to select and use messages from or to a particular user that are 
associated with many folder names. 
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When you specify more than one character substring, VMS MAIL performs 
a logical AND operation to find the messages that contain the correct 
substring. 

Message Arrival Date and Time 


You can also select a message or group of messages based on their arrival 
time, that is, when you received them. Applications select messages 
according to two criteria as follows: 


¢ Messages received before a specified date or time or both. 


e Messages received since a specified date or time or both. 


VMS MAIL searches the mail file and selects messages whose primary key 
(date and time) matches the date and time specified in your application. 


Message Characteristics 


You can select messages based on MAIL system flag values that indicate 
the following message characteristics: 


e New 
e Marked 
e Replied 


For example, you can select unread messages in order to display them or 
to display a message you have marked. 


9.9.2 Reading and Printing Messages 


After a message is selected, an applicetion iteratively retrieves the 
contents of the bodypart record by record. The message can be retrieved 
using MAIL$MESSAGE_GET and can then be stored in a buffer or file. 


Displaying a Message 


To display a message on the terminal screen, you should store the message 
in a buffer and use the host programming language command that directs 
data to the screen. 


Printing a Message 


To print a message on a print queue on your system, you should write the 
message to an external file and use the SYS$SNDJBC system service to 
manage print jobs and define queue characteristics. 


9.9.3. Modifying Messages 
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Message modification using MAIL$MESSAGE_MODIFY involves setting 
fiags that identify a message or group of messages as having certain 
characteristics. The following table summarizes bit offsets that modify flag 
settings: 
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Symbol Meaning 


MAIL$V_REPLIED Flagged as answered 
MAIL$V_MARKED Flagged for display purposes 


9.9.4 Copying and Moving Messages 


You can copy messages between folders within a mail file or between 
folders in different mail files using MAIL$MESSAGE_COPY. VMS MAIL 
copies the message from the source folder to the destination folder leaving 
the original message intact. 


Similarly, you can move messages between folders within a mail file or 
between folders in different mail files using MAIL$MESSAGE_COPY with 
the item code MAIL$_ MESSAGE_DELETE. VMS MAIL moves a message 
by copying the message from the source folder and copying the message to 
the destination folder. You must specify a folder name. 


When you move a message to another folder within the same mail file, you 
are changing the message’s secondary key—its folder name. 


9.9.4.1 Creating Folders 
You can create a folder in a specified mail file whenever you attempt to 
copy or move a message to a nonexistent folder. When you create a folder, 
you are assigning a previously nonexistent folder name to a message as its 
secondary key. 


Your application can include a user-written folder action routine that 
notifies you that the folder does not exist and accepts input to create the 
folder. 


9.9.4.2 Deleting Folders 
You can delete a folder by moving all of the messages within the source 
folder to another folder in the same mail file or to a folder in another mail 
file. In this case, MAIL associates messages that are moved with a new 
folder name. 


You can also delete a folder by deleting all of the messages in a folder. 
MAIL associates messages designated for deletion with the wastebasket 
folder name. 


In either case, the original folder name—the secondary key—no longer 
exists. 


9.9.4.3 Creating Mail Files 
Similarly, you can create a mail file whenever you attempt to copy or move 
a message to a nonexistent mail file. 


Your application can include a user-written mail file action routine that 
notifies you that the mail file does not exist and accepts input to create the 
mail file. 
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Mail file creation involves creating the mail file and then copying or 
moving the message to the new mail file. If the message is shorter than 
3 blocks, VMS MAIL stores the message in the mail file. Otherwise, VMS 
MAIL places a pointer to the message in the newly created mail file. 


9.9.5 Deleting Messages 


To delete a message, you need to know its message identification number. 
Applications can retrieve the message identification number by specifying 
the item code MAIL$_ MESSAGE_ID when selecting a message or group of 
messages with MAIL$MESSAGE_SELECT. 


When you delete all messages with the same secondary key (folder name) 
using MAIL$MESSAGE_DELETE and specifying the item code MAIL$_ 
MESSAGE_ID, you have deleted the folder. 





9.10 Send Context 


Send context processing involves creating and sending new and existing 
messages. Table 9-7 summarizes send routines. 


Table 9-7 Send Routines 


Routine Description 

MAIL$SEND_ABORT Aborts a send operation 
MAIL$SEND_ADD_ADDRESS Adds an addressee to the address list 
MAIL$SEND_ADD_ATTRIBUTE Constructs the message header 
MAIL$SEND_ADD_BODYPART Constructs the body of the message 
MAIL$SEND_BEGIN Initiates send processing 
MAILS$SEND_END Terminates send processing 
MAIL$SEND_MESSAGE Sends a message 


Initiating the Send Context 


You can invoke the send context directly if you are ereating a new message. 
Otherwise, to access an existing message, you must open the mail file that 
contains the message, select the message, and retrieve it. 


Terminating the Send Context 
You must terminate the send context explicitly using MAIL$SEND_END. 
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9.10.1 Sending New Messages 


You can send new or existing messages to yourself and other users. 


9.10.1.1 Creating a Message 
You create new messages using send context routines. If you want to 
create and send a new message, you do not need to initiate any other 
context. As mentioned earlier, a message consists of two parts—the 
message header and the message bodypart. 


Constructing a message involves building each part of the message 
separately using the following routines: 


¢ MAIL$SEND_ADD_ATTRIBUTE 
e MAIL$SEND_ADD_BODYPART 


9.10.1.1.1 Constructing the Message Header 
Each field of the message header is a message attribute. You can 
specify one or more attributes for inclusion in the message header 
using MAIL$SEND_ADD_ATTRIBUTE. During successive calls to 
MAIL$SEND_ADD_ATTRIBUTE, an application specifies the specific 
message attribute to be constructed. 


If you do not specify the From: or To: fields, MAIL provides this 
information from the address list. 


9.10.1.1.2 Constructing the Body of the Message 
To construct a message, an application must specify a series of calls to 
MAIL$SEND_ADD_BODYPART to build a message from successive text 
records contained in a buffer or file. 


If the body of the message is located in a file, you can build the bodypart 
with one call to MAIL$SEND_ADD_BODYPART by specifying its file 
name. 


9.10.1.2 Creating an Address List 
You must create an address list in order to send a message. The address 
list is a file or buffer of addressees to whom you want to send the message. 
Each entry in the address list is a valid username on your system or on 
another system connected to your system by DECnet-—VAX. 


Adding Usernames to the Address List 


Usernames are added one at a time to the address list using one or more 
calls to MAIL$SEND_ADD_ADDRESS. 


Username Types 


There are two types of usernames—direct and carbon copy addressees. 
Direct and carbon copy addressees correspond to usernames in the To: and 
CC: fields of the message header. 
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9.10.2 Sending Existing Messages 


Sending an existing message involves many tasks as well as initiating the 
mail file context and message context. The following table summarizes the 
tasks and routines involved in sending an existing message: 


Task Routine 
Open a mail file MAIL$MAILFILE_OPEN 
Select the message MAIL$MESSAGE_SELECT 
Retrieve the message MAILSMESSAGE_GET 
Construct the message 
Construct the message header MAIL$SEND_ADD_ATTRIBUTE 
Construct the message bodypart MAIL$SEND_ADD_BODYPART 
Create an address list MAIL$SEND_ADD_ADDRESS 
Send the message MAIL$SEND_MESSAGE 


9.10.3 Send Action Routines 


Once you have created an address list and constructed a message, you 
can send the message using MAIL$SEND_MESSAGE. Optional success 
and error action routines handle signaled success and error events in a 
synchronous manner. 


For example, If DECnet-VAX returns messages indicating that it might 
not be possible to complete a send operation to some users in your address 
list, a user-specified send action routine might prompt the sender for 
permission to continue the send operation. 


9.10.3.1 Success Action Routines 


A success action routine performs a task upon successful completion of a 
send operation. 


9.10.3.2 Error Handling Routines 


An error action routine is a user-written error handler that signals error 
conditions during a send operation. 


9.10.3.3 Aborting a Send Operation 
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Under certain circumstances, you might want to terminate a send 
operation in progress using MAIL$SEND_ABORT. In this instance, you 
can use an asynchronous system trap (AST) routine that contains a call 
to MAIL$¢SEND_ABORT to abort the send operation whenever the user 
presses the Ctrl/c key sequence. 
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9.11 User Profile Context 


The user profile processing context functions as a system management 
tool for customizing the programming and interactive VMS MAIL 
environments. It lets individual users modify their default processing 
characteristics. 


The user common database VMSMAIL_PROFILE.DATA contains 
information that application programs and VMS MAIL use for processing 
in any context. 


User Context Routines 


Table 9-8 summarizes the user context routines. 


Table 9-8 User Profile Context Routines 





Routine Description 

MAIL$USER_BEGIN Initiates user profile context 

MAIL$USER_DELETE_INFO Deletes a user profile entry 

MAIL$USER_END Terminates user profile context 

MAIL$USER_GET_INFO . Retrieves information about a user from the user 
profile 

MAILSUSER_SET_INFO Adds or modifies a user profile entry 


initiating the User Context 


You can invoke the user context directly. 


Terminating the User Context 


You must terminate the user context with MAIL$SUSER_END. Terminating 
the user context deallocates virtual memory. 


9.11.1 User Profile Entries 


A user profile entry is a dynamic record. VMS MAIL creates a user profile 
entry automatically for the calling process if it does not exist. The callable 
and user interfaces of the MAIL utility use the data contained in the user 
profile entry. The user profile consists of fields as described in the sections 
that follow. 


MAIL Subdirectory 


A MAIL subdirectory is the location—that is, the disk and directory 
specification—of your mail files. When you define a MAIL subdirectory, 
you are creating a subdirectory in which the specified mail file and 
associated external messages are to reside. For example: 


SDISK5: [MAILUSER. COMMON .MAIL] 
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The subdirectory [.common.mail] represents the MAIL subdirectory 
specification defined in the user profile entry. This subdirectory contains 
the mail file (for example, MAIL.MAI) and any external messages 
associated with the mail file. The disk and directory specification 
$DISK5:[MAILUSER] is defined in the user authorization file (UAF). 


Flags 


User profile flags can be set to enable or disable automatic purging of 
deleted mail, automatic self-copy when forwarding, replying, or sending 
messages, and use of the CC prompt. 


Form 


The form field of the user profile entry defines the default print form to be 
used by print batch jobs. The string you specify as the default form must 
match a valid print form in use on your system. 


Forwarding Address 


A forwarding address lets you receive messages to your account on 
another system or to have your messages sent to another user either 

on your system or another system. You must specify valid nodenames and 
usernames. 


Personal Name 


A personal name is a user-specified character string. For example, a 
personal name might include your entire name and phone number. Any 
phrase beginning with alphabetic characters up to a maximum of 255 
alphanumeric characters is valid. 


Queue Name 


The queue name field defines the default print queue on your system 
where your print jobs are sent. 


9.11.1.1 Adding User Profile Entries to the User Common Database 


Ordinarily, VMS MAIL creates a user profile entry for the calling process 
if one does not already exist. A system management application might 
create entries for other users. When you specify the item code MAIL$_ 
USER_CREATE_IF using MAIL$USER_SET_INFO, VMS MAIL creates a 
user profile entry if it does not already exist. 





9.11.1.2 Modifying or Deleting User Profile Entries 
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The calling process can modify, delete, or retrieve its own user profile entry 
without privileges. 


The following table summarizes the privileges required to modify or delete 
user profile entries that do not belong to the calling process: 


Procedure Privilege Function 
MAILSUSER_SET_INFO SYSPRV To modify another user’s 
profile entry 


9.12 


Procedure 


MAIL$USER_GET_INFO 
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Privilege Function 


To retrieve information about 
another user 


SYSNAM or SYSPRV 





Input Item Codes 


Input item codes direct the called routine to read data from a buffer or file 
and perform a task. Table 9-9 summarizes input item codes. 


Table 9-9 Input Item Codes 
Item Code 

Mail File Context 
MAIL$_MAILFILE_DEFAULT_NAME 


MAIL$_MAILFILE_FOLDER_ROUTINE 
MAIL$_MAILFILE_FULL_CLOSE 


MAIL$_MAILFILE_NAME 
MAIL$_MAILFILE_RECLAIM 


MAIL$_MAILFILE_USER_DATA 
MAIL$_MAILFILE_WASTEBASKET_NAME 


Message Context 


MAIL$_MESSAGE_AUTO_NEWMAIL 
MAIL$_MESSAGE_BACK 
MAIL$_MESSAGE_BEFORE 
MAIL$_MESSAGE_CC_SUBSTRING 


MAIL$_MESSAGE_CONTINUE 
MAIL$_MESSAGE_DEFAULT_NAME 
MAIL$_MESSAGE_DELETE 


MAIL$_MESSAGE_FILE_ACTION 


MAIL$_MESSAGE_FILE_CTX 
MAIL$_MESSAGE_FILENAME 


MAIL$_MESSAGE_FOLDER_ACTION 


Function 


Specifies the location (disk and directory) of the default mail file 
MAIL.MAI. 


Displays folder names within a specified mail file. 


Requests that the wastebasket folder be purged and that a convert 
/reclaim operation be performed, if necessary. 


Specifies the name of a mail file to be opened. 


Overrides the deleted bytes threshold and and requests a reclaim 
operation. 


Passes a longword of user context data to an action routine. 
Specifies a new name for the wastebasket in a specified mail file. 


Places newly read messages in the MAIL folder automatically. 
Returns the first record of the preceding message. 
Selects a message before a specified date and time. 


Specifies a character string that must match a substring in the CC: 
field of the specified message. 


Returns the next text record of the current message. 
Specifies the default mail file specification. 


Deletes a message in the current folder after the message has 
been copied to a new folder. 


Specifies a user-written routine that is called if a mail file is to be 
created. 


Specifies mail file context received from MAIL$MAILFILE_BEGIN. 


Specifies the name of a mail file to which the message is to be 
moved. 


Specifies a user-written routine that is called if a folder is to be 
created. 


(continued on next page) 
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Table 9-9 (Cont.) 
Item Code 


Input Item Codes 


Message Context 


MAIL$_MESSAGE_FLAGS 
MAIL$_MESSAGE_FLAGS_MBZ 
MAIL$_MESSAGE_FOLDER 
MAIL$_MESSAGE_FROM_SUBSTRING 


MAIL$_MESSAGE_NEXT 


MAIL$_MESSAGE_SINCE 
MAIL$_MESSAGE_SUBJ_SUBSTRING 


MAIL$_MESSAGE_TO_SUBSTRING 


MAIL$_MESSAGE_USER_DATA 


Send Context 


MAIL$_SEND_CC_LINE 
MAIL$_SEND_DEFAULT_NAME 
MAIL$_SEND_ERROR_ENTRY 


MAIL$_SEND_FID 
MAIL$_SEND_FILENAME 
MAIL$_SEND_FROM_LINE 


MAIL$_SEND_PERS_NAME 
MAIL$_SEND_NO_PERS_NAME 


MAIL$_SEND_RECORD 


MAIL$_SEND_SUBJECT 
MAIL$_SEND_SUCCESS_ENTRY 


MAIL$_SEND_TO_LINE 
MAIL$_SEND_USER_DATA 
MAIL$_SEND_USERNAME 
MAIL$_SEND_USERNAME_TYPE 
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Function 


Specifies MAIL system flags to use when selecting messages. 
Specifies MAIL system flags that must be zero. 
Specifies the name of the target folder for moving messages. 


Specifies a character string that must match a substring in the 
From: field of the specified message. 


Specifies the message identification number of the message on 
which an operation is to be performed. 


Returns the first record of the message following the current 
message. 


Selects a message received since a specified date and time. 


Specifies a character string that must match a substring in the 
Subject: field of the specified message. 


Specifies a character string that must match a substring in the To: 
field of the specified message. 


Specifies a longword to be passed to the folder and mail file action 
routines. 


Specifies the CC: field text. 
Specifies the default file specification of a text file to be opened. 


Specifies a user-written routine to process errors that occur during 
a send operation. 


Specifies the file identifier. 
Specifies the input file specification of a text file to be opened. 
Specifies the From: field text. 


Specifies the personal name string 
Specifies that no personal string be used. 


Specifies the descriptor of a text record to be added to the body of 
a message. 


Specifies the Subject: field text. 


Specifies a user-written routines to process successfully completed 
events during a send operation. 


Specifies the To: field text. 

Specifies a longword passed to the send action routines. 
Adds a specified username to the address list. 

Specifies the type of username added to the address list. 


(continued on next page) 
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Item Code 


Input Item Codes 


User Context 


MAIL$_USER_CREATE_IF 
MAIL$_USER_FIRST 
MAIL$_USER_NEXT 


MAIL$_USER_SET_AUTO_PURGE 
MAIL$_USER_SET_NO_AUTO_PURGE 


MAIL$_USER_SET_CC_PROMPT 
MAIL$_USER_SET_NO_CC_PROMPT 


MAIL$_USER_SET_COPY_FORWARD 
MAIL$_USER_SET_NO_COPY_FORWARD 


MAIL$_USER_SET_COPY_REPLY 
MAIL$_USER_SET_NO_COPY_REPLY 


MAIL$_USER_SET_COPY_SEND 
MAIL$_USER_SET_NO_COPY_SEND 


MAIL$_USER_SET_EDITOR 
MAIL$ USER_SET NO EDITOR 


MAIL$_USER_SET_FORM 
MAIL$_USER_SET_NO_FORM 


MAIL$_USER_SET_FORWARDING 
MAIL$_USER_SET_NO_FORWARDING 


MAIL$_USER_SET_NEW_MESSAGES 


MAIL$_USER_SET_PERSONAL_NAME 
MAIL$_USER_SET_NO_PERSONAL_ 
NAME 


MAIL$_USER_SET_QUEUE 
MAIL$_USER_SET_NO_QUEUE 


MAIL$_USER_SET_SUB_DIRECTORY 
MAIL$_USER_SET_NO_SUB_DIRECTORY 


MAIL$_USER_USERNAME 
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Function 


Creates a user profile entry. 
Returns information about the first user in the user profile database. 


Returns information about the next user in the user profile 
database. 


Sets the automatic purge flag. 
Clears the automatic purge flag. 


Sets the CC prompt flag. 
Clears the CC prompt flag. 


Sets the copy self forward flag. 
Clears the copy self forward flag. 


Sets the copy self reply flag. 
Clears the copy self reply flag. 


Sets the copy self send flag. 
Clears the copy self send flag. 


Specifies the default editor. 
Clears the default editor field. 


Specifies the default print form string. 
Clears the default print form field. 


Specifies the forwarding address string. 
Clears the forwarding address field. 


Specifies the new messages count. 


Specifies the personal name string. 
Clears the personal name field. 


Specifies the default print queue name string. 
Clears the default print queue name field. 


Specifies a MAIL subdirectory. 
Clears the MAIL subdirectory field. 


Specifies the user profile entry to be modified. 





Output Item Codes 


Output item codes direct the called routine to return data to a buffer or file 
which is then available for use by the application. Table 9-10 summarizes 
output item codes. 
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Table 9-10 Output Item Codes 


Item Code 


Mail File Context 


Function 





MAIL$_MAILFILE_INDEXED 
MAIL$_MAILFILE_DIRECTORY 
MAIL$_MAILFILE_RESULTSPEC 
MAIL$_MAILFILE_WASTEBASKET 
MAIL$_MAILFILE_DELETED_BYTES 


RAAT $ MAI FILE MESSAGES DELETED 


WIrliuw tL.d | me ae i 


MAIL$_MAILFILE_DATA_RECLAIM 
MAIL$_MAILFILE_DATA_SCAN 
MAIL$_MAILFILE_INDEX_RECLAIM 
MAIL$_MAILFILE_TOTAL_RECLAIM 


Determines whether the mail file format is indexed-sequential. 
Returns the mail file subdirectory specification to the caller. 
Returns the result mail file specification. 

Returns the wastebasket folder name for the specified file. 
Returns the number of deleted bytes in a specified mail file. 
Returns the number of deleted messages. 

Returns the number of data buckets reclaimed. 

Returns the number of data buckets scanned. 

Returns the number of index buckets reclaimed. 


Returns the total number of bytes reclaimed. 





Message Context 





MAIL$_MESSAGE_BINARY_DATE 
MAIL$_MESSAGE_CC 
MAIL$_MESSAGE_CURRENT_ID 
MAIL$_MESSAGE_DATE 
MAIL$_MESSAGE_EXTID 


MAIL$_MESSAGE_FILE_CREATED 
MAIL$_MESSAGE_FOLDER_CREATED 
MAIL$_MESSAGE_FROM 
MAIL$_MESSAGE_RECORD 
MAIL$_MESSAGE_RECORD_TYPE 
MAIL$_MESSAGE_REPLY_PATH 
MAIL$_MESSAGE_RESULTSPEC 
MAIL$_MESSAGE_RETURN_FLAGS 
MAIL$_MESSAGE_SELECTED 
MAIL$_MESSAGE_SENDER 
MAIL$_MESSAGE_SIZE 
MAIL$_MESSAGE_SUBJECT 
MAIL$_MESSAGE_TO 


Returns the date and time received as a binary value. 

Returns the text in the CC: field of the current message. 

Returns the message identification number of the current message. 
Returns the message creation date string. 


Returns the external message identification number of the current 
message. 


Returns the value of the mail file created flag. 

Returns the value of the folder created flag. 

Returns the text in the From: field of the current messsage. 
Returns a record from the current message. 

Returns the record type. 

Returns the reply path. 

Returns the resultant mail file specification. 

Returns the MAIL system flag value of the current message. 
Returns the number of selected messages. 

Returns the name of the sender of the current message. 
Returns the size in records of the current message. 

Returns the text in the Subject: field of the specified message. 
Returns the text in the To: field of the specified message. 
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Table 9-10 (Cont.) Output Item Codes 


Item Code Function 


Send Context 


MAIL$_SEND_COPY_FORWARD Returns the value of the caller’s copy forward flag. 
MAIL$_SEND_COPY_REPLY Returns the value of the caller’s copy reply flag. 
MAIL$_SEND_COPY_SEND Returns the value of the caller’s copy send flag. 
MAIL$_SEND_RESULTSPEC Returns the resultant file specification of the file to be sent. 
MAIL$_SEND_USER Returns the process owner’s username. 


User Context 


MAIL$_USER_AUTO_PURGE Returns the value of the automatic purge mail flag. 
MAIL$_USER_CAPTIVE Returns the value of the UAF captive flag. 
MAIL$_USER_CC_PROMPT Returns the value of the CC prompt flag. 
MAIL$_USER_COPY_FORWARD Returns the value of the copy self forward flag. 
MAIL$_USER_COPY_REPLY Returns the value of the copy self reply flag. 
MAIL$_USER_COPY_SEND Returns the value of the copy self send flag. 
MAIL$_USER_EDITOR Returns the name of the default editor. 
MAIL$_USER_FORM Returns the default print form string. 
MAIL$_USER_FORWARDING Returns the forwarding address string. 
MAIL$_USER_FULL_DIRECTORY Returns the complete directory path of the mail file subdirectory. 
MAIL$_USER_NEW_MESSAGES Returns the new message count. 
MAIL$_USER_PERSONAL_NAME Returns the personal name string. 
MAIL$_USER_QUEUE Returns the default queue name string. 
MAIL$_USER_RETURN_USERNAME Returns the username string. 
MAIL$_USER_SUB_DIRECTORY Returns the subdirectory specification. 


Examples of Using MAIL Routines 


The following section contains programming examples. Example 9-1 is a 
C program that sends a MAIL message to another user. 
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Example 9-1 Sending a File 





/* send_message.c */ 


#include <stdio> 
#include <descrip> 
#include <ssdef> 
#include <maildef> 
#include <nam> 


typedef struct itmlst 
{ 
short buffer length; 
short item_code; 
long buffer address; 
long return_length_address; 
} ITMLST; 
anale 
send_context = 0 


’ 


ITMLST 
nulllist[] = { {0,0,0,0} }; 
int 
getline(char *line, int max) 
{ 
if (fgets(line, max, stdin) == NULL) 
return 0; 
else 
return strlen(line); 
} 
int 
main (int argc, char *argv[]) 


{ 
char 
to_user[{NAMSC_MAXRSS], 
subject_line[NAM$C_MAXRSS], 
file[NAM$C_MAXRSS], 
resultspec [NAMS$C_MAXRSS] 


tA 


long resultspeclen; 

int 
status = SS$_NORMAL, 
file len = 0, 
subject_line len = 0, 
to_user_len = 0 


* 
, 
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ITMLST 
address itmlst[] = { 
{sizeof (to_user), MAIL$_SEND_USERNAME, to_user, &to_user_len}, 
{0,0,0,0}}, 
bodypart_itmlst[] = { 
{sizeof (file), MAIL$_SEND FILENAME, file, &file_len}, 
{0,0,0,0}}, 
out_bodypart_itmlst[] = { 
{sizeof (resultspec), MATIL$ SEND RESULTSPEC, resultspec, &resultspeclen}, 
{0,0,0,0}}, 
attribute _itmlst[] = { 
{sizeof (to_user), MAILS SEND _TO_LINE, to_user, &to_user_len}, 
{sizeof (subject_line), MAILS SEND SUBJECT, subject_line, &subject_line_len}, 
{0,0,0,0}} 


™“e 


status = mailSsend_begin(&send_context, é&nulllist, énulllist); 
if (status != SS$_NORMAL) 
exit (status); 


/* Get the destination and add it to the message */ 
Prince ("Loe 4) 5 
to_user[{getline(to_user, NAM$C_MAXRSS) - 1] = NULL; 


address itmist[0].buffer_length = strlen(to_user); 
address itmlst[0].buffer address = to_user; 


status = mail$send_add_address(&send_context, address itmlst, énulllist); 
if (status != SS$_ NORMAL) 
return(status) ; 


/* Get the subject line and add it to the message header */ 
printt ("Subject : "); 
subject_line[getline(subject_line, NAM$C_MAXRSS) - 1] = NULL; 


/* Displayed TO: line */ 
attribute itmlst[0].buffer length = strlen(to_user) ; 
attribute itmlst[0].buffer address = to_user; 


/* Subject: line */ 
attribute itmlst[1].buffer length = strlen(subject_line) ; 
attribute itmlst[1].buffer_ address = subject_line; 


status = mail$send_add_attribute(&send_context, attribute _itmlst, é&nulllist); 
if (status != SS$_NORMAL) 
return(status) ; 


/* Get the file to send and add it to the bodypart of the message */ 
priantte( "Fides ") > 
file[getline(file, NAM$C_MAXRSS) - 1] = NULL; 


bodypart_itmlst[0].buffer_length = strlen(file); 
bodypart_itmlst[0].buffer_address = file; 


status = mail$send_add_bodypart (&send_context, bodypart_itmlst, out_bodypart_itmlst); 
if (status != SS$_NORMAL) 
return(status) ; 


resultspec[resultspeclen] = ’\0’; 
printf("Full file spec actually sent: [%s]\n", resultspec) ; 
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/* Send the message */ 
status = mailSsend_message(&send_context, nulllist, nulllist); 
if (status != SS$ NORMAL) 

return(status); 


/* Done processing witht the SEND context */ 
status = mailSsend_end(&send_context, nulllist, nulllist); 
if (status != SS$ NORMAL) 

return (status) ; 


return (status); 


~ 





Example 9-2 is a C program that displays a user’s folders and returns how 
many messages are in each folder. 


Example 9-2 Displaying Folders 





/* show _folders.c */ 


#include <stdio> 
#include <descrip> 
#include <ctype> 
#include <ssdef> 
#include <maildef> 


typedef struct itmlst 
{ 

short buffer length; 

short item_code; 

long buffer address; 

long return_length_address; 
} ITMLST; 


struct node 


{ 


struct node *next; /* Next folder name node */ 

char *folder_name; /* Zero terminated folder name */ 
bi 
int 


folder routine(struct node *list, struct dscSdescriptor *name) 
{ 
if (name->dsc$w_length) 
{ 
while (list->next) 
list = list->next; 


list->next = malloc(sizeof (struct node) ); 

list = list->next; 

list->next = 0; 

list->folder_name = malloc (name->dsc$w_length + 1); 

strncpy (list->folder_name,name->dsc$a_pointer, name->dsc$w_length) ; 
list->folder_name[name->dsc$w_length] = ’\0’; 
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} 
return (SS$_NORMAL) ; 
} 


main (int argc, char *argv[]) 
{ 
struct node list = {0,0}; 
int 
message context = 0, 
file context = 0, 
messages selected = 0, 
total _ folders = 0, 
total_messages = 0 


‘ 


ITMLST 
nulllist[] = {{0,0,0,0}}, 
message_in_itmlst[] = { 


{sizeof (file context) ,MAIL$ MESSAGE FILE _CTX, &file context, 0}, 
{0, 0, 0, O}}, 
mailfile_ info itmlst[{] = { 
{4,MAIL$ MAILFILE FOLDER_ROUTINE, folder_routine,0}, 
{4,MAILS MAILFILE USER_DATA, élist,0}, 
{0,0,0,0}}, 
message _select_in itmlst[] = { 
{0,MAIL$ MESSAGE FOLDER, 0,0}, 
{0, 0, 0, O}}, 
message_select_out_itmlst[] = { 
{sizeof (messages_selected) ,MAIL$ MESSAGE SELECTED, &messages_selected,0}, 
{0,0,0,0}}; 


if (mail$mailfile_begin(&file_context, nulllist, nulllist) == SS$_NORMAL) { 
if (mail$mailfile open(&file context, nulllist, nulllist) == SS$_NORMAL) { 
if (mail$mailfile info file(&file context, 
mailfile_info_itmlst, 
nulllist) == SS$_NORMAL) { 
if (mail$Smessage_ begin (&message_ context, 
message_in_itmlst, 
nulllist) == SS$ NORMAL) { 
struct node *tmp = é&list; 


while (tmp->next) { 
tmp = tmp->next; 
message _select_in itmlst[0].buffer_address = tmp->folder_name; 
message_select_in_itmlst[0].buffer_length = strlen(tmp->folder_name) ; 
if (mail$message_select (&message_context, 
message_select_in_itmlst, 
message_select_out_itmlst) == SS$ NORMAL) { 
printf("Folder %s has %d messages\n", 
tmp->folder_ name, messages selected); 
total_messages += messages_selected; 
total folders++; 
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printf ("Total of %d messages in %d folders\n",total_messages, total_folders); 
} 
mail$message_end(&message context, nulllist, nulllist); 
} 
mail$mailfile close(&file context, nulllist, nulllist); 


} 


mail$mailfile_end(&file_context, nulllist, nulllist); 


} 


~ 





Example 9-3 is a C program that displays fields in the user’s MAIL 
profile. 


Example 9-3 Displaying User Profile Information 





/* show_profile.c */ 


#include <stdio> 
#include <ssdef> 
#include <jpidef> 
#include <maildef> 
#include <stsdef> 
#include <ctype> 
#include <nam> 


struct itmlst 
{ 
short buffer_length; 
short item_code; 
long buffer address; : 
long return_length_address; 
Me 


int 
user context = 0 


: 
‘, 


struct 
itmlst nulllist[] = { {0,0,0,0} }; 


int 
main (int argc, char *argv[]) 
{ 


int 
userlen = 0, 
/* return length of strings */ 


editor_len = 0, 
form_len = 0, 
forwarding len = 0, 
full_directory_len = 0, 
personal name_len = 0, 
queue_len = 0, 


/* Flags */ 


auto_purge = 0, 
cc_prompt = 0, 
copy forward = 0, 
copy_reply = 0, 
copy_send = 0 


. 
’ 





(continued on next page) 


MAIL-30 


MAIL Routines 
9.14 Examples of Using MAIL Routines 


Example 9-3 (Cont.) Displaying User Profile Information 





char 
user[(13], 
editor [NAMSC_MAXRSS], 
form[NAMSC_MAXRSS], 
forwarding [NAM$C_MAXRSS], 
full_directory [NAMS$C_MAXRSS], 
personal name [(NAM$C_MAXRSS], 
queue [NAM$C_MAXRSS] 


, 


short 
new_messages = 0 


. 
’ 


struct itmist 
jpi_list{] = { 
{sizeof(user) - 1, JPIS$_USERNAME, user, é&userlen}, 
{0,0,0,0}}, 
user _itmlst[] = { 
{0, MAIL$_USER_USERNAME, 0, 0}, 
{0,0,0,0}}, 
out_itmlst[] = { 
/* Full directory spec */ 
{sizeof (full_directory) ,MAIL$_USER_FULL_DIRECTORY, full_ directory, &full_ directory len}, 
/* New message count */ 
{sizeof (new_messages), MAILS USER_NEW_MESSAGES, &new_messages, 0}, 
/* Forwarding field */ 
{sizeof (forwarding), MAIL$ USER_FORWARDING, forwarding, &forwarding_len}, 
/* Personal name field */ 
{sizeof (personal_name), MAIL$_USER_PERSONAL_NAME, personal_name, &personal_name_len}, 
/* Editor field */ 
{sizeof(editor), MAIL$ USER_EDITOR, editor, &editor_len}, 
/* CC prompting flag */ 
{sizeof(cc_prompt), MAIL$ USER_CC_PROMPT, &cc_prompt, 0}, 
/* Copy send flag */ 
{sizeof (copy send), MAIL$ USER_COPY_SEND, &copy_send, 0}, 
/* Copy reply flag */ 
{sizeof(copy reply), MAIL$ USER_COPY_REPLY, &copy reply, 0}, 
/* Copy forward flag */ 
{sizeof(copy_ forward), MAILS USER_COPY_FORWARD, &copy forward, 0}, 
/* Buto purge flag */ 
{sizeof (auto_purge), MAIL$_USER_AUTO PURGE, &auto_purge, 0}, 
/* Queue field */ 
{sizeof(queue), MAIL$ USER_QUEUE, queue, &queue_len}, 
/* Form field */ 
{sizeof(form), MAIL$ USER_FORM, form, &form_len}, 


{0,0,0,0}}; 
int 
status = SS$_ NORMAL 


. 
, 


/* Get a mail user context */ 
status = MAILSUSER_BEGIN(&user_context, 
énulllist, 
énulllist); 
if (status != SS$_ NORMAL) 
return(status) ; 


if (arge > 1) { 
strepy (user,argv[1]); 
} 
else 
{ 
sys$getjpiw(0,0,0,jpi_list,0,0,0); 
user[userlen] = '\0‘'; 


}e 


while (isspace (user [--userlen])) 
user[userlen] = ’\0/; 


user_itmlst[0].buffer_length = strlen(user); 
user_itmlst[0].buffer_address = user; 
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status = MAILSUSER_GET_INFO(&user_context, user_itmlst, out_itmlst); 
if (status != SS$ NORMAL) 
return (status); 


/* Release the mail USER context */ 
status = MAILSUSER_END(&user_context, &nulllist, &nulllist); 
if (status != SS$_ NORMAL) 

return (status) ; 


/* display the information just gathered */ 


full_directory(full_directory len} = ’\0'; 
printf("Your mail file directory is %s.\n", full_directory) ; 
printf("You have %d new messages.\n", new_messages) ; 


forwarding {forwarding_len] = ’\0’; 
if (strlen(forwarding) == 0) 
printf("You have not set a forwarding address.\n"); 
else 
printf("Your mail is being forwarded to %s.\n", forwarding); 


personal _name[personal_name_len] = ‘\0’; 
printf("Your personal name is \"%s\"\n", personal_name) ; 


editor[editor len] = '\0'; 


if (strlen(form) == 0) 
printf("You have not specified an editor.\n"); 
else 


printf("Your editor is %s\n", editor); 


printf("CC prompting is %s.\n", (cc_prompt == TRUE) ? "disabled" : "enabled"); 


printf ("Automatic copy to yourself on"); 
if (copy _send == TRUE) 
printf(" SEND"); 
if (copy_reply == TRUE) { 
if (copy_send == TRUE) 
printft(","); 
printf(" REPLY"); 
} 
if (copy forward == TRUE) { 
if ((copy_reply == TRUE) |! (copy _send == TRUE)) 
printf(","); 
printf(" FORWARD") ; 
} 
if ((copy_reply == FALSE) && (copy _send == FALSE) && (copy_forward == FALSE) ) 
printf(" Nothing"); 
printf ("\n"); 


printf ("Automatic deleted message purge is %s.\n", (auto_purge == TRUE) ? "disabled" : "enabled"); 


queue [queve_len] = ’\0’; 
if (strlen(form) == 0) 

printf("You have not specified a default queue.\n"); 
else 


printf("Your default print queue is %s.\n", queue); 


form[form_len] = ’\0’; 


1£ (strlen(form) == 0) 
printf("You have not specified a default print form.\n"); 
else 


printf("Your default print form is %s.\n", form); 
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9.15 MAIL Routines 
The following pages describe the individual MAIL routines. 
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MAIL$MAILFILE_BEGIN 


Inititates mail file processing. 





MAIL$MAILFILE_BEGIN context, in_item_list, 
out_item_list 





VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context — 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Mail file context information to be passed to other mail file routines. The 
context argument is the address of a longword that contains mail file 
context information. 


You should specify the value of this argument as 0 in the first of a 
sequence of calls to mail file routines. In the following calls, you should 
specify the mail file context value returned by this routine. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by a longword value of 0. 


MAIL Utility Routines 
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The following diagram depicts the format of a single item descriptor: 
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In_item_list Item Descriptor Fields 


buffer length 


A word specifying the length (in bytes) of the buffer that supplies the 
information needed by the routine to process the specified item code. The 
required length of the buffer depends on the item code specified in the 
item code field of the item descriptor. If the value of buffer length is too 
small, the routine truncates the data. 


item code 


A word containing a user-supplied symbolic code that specifies an option 
for the MAIL operation. These codes are defined by the $MAILDEF macro. 
See Input Item Codes for a description of these codes. 


buffer address 
A longword containing the address of the buffer that supplies information 
to the routine. 


return length address 
This field is not used. 


Input Item Codes 
None. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 
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The following diagram depicts the format of a single item descriptor: 
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Out_item_list Item Descriptor Fieids 

buffer length 

A word containing a user-supplied integer specifying the length (in bytes) 
of the buffer in which the routine is to write the information. The length 
of the buffer needed depends on the item code specified in the item code 
field of the item descriptor. If the value of buffer length is too small, the 
routine truncates the data. 


item code 


A word containing a user-supplied symbolic code specifying the item of 
information that the routine is to return. These codes are defined by 
the $MAILDEF macro. See Output Item Codes for a description of these 
codes. 


buffer address 
A longword containing the user-supplied address of the buffer in which the 
routine is to write the information. 


return length address 


A longword containing the user-supplied address of a word in which the 
routine writes the actual length in bytes of the information it returns. 


Output Item Codes 


MAIL$_MAILFILE_MAIL_DIRECTORY 

When you specify MAIL$_MAILFILE_MAIL_DIRECTORY, 
MAIL$MAILFILE_BEGIN returns the mail directory specification to 
the caller. The buffer address field of the item descriptor points to a 
buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 





DESCRIPTION MAIL$MAILFILE_BEGIN creates and initiates a mail file context for calls 
to other mail file routines. 
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CONDITION . 

VALUES SS$_NORMAL Normal splieibea compreton: | 
MAIL$_INVITMCOD The specified item code is invalid. 

RETURNED MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
SS$_ACCVIO Access violation. 


Any condition value returned by LIBSGET_VM, $GETJPIW, and $GETSYI. 
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MAIL$MAILFILE_CLOSE 


Closes the currently open mail file. 





FORMAT 


MAIL$MAILFILE_CLOSE context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 

Mail file context information to be passed to mail file routines. The 


context argument is the address of a longword that contains mail file 
context information returned by MAIL$MAILFILE_BEGIN. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of an input item 
descriptor. 


Input Item Codes 


MAIL$ MAILFILE_FULL_CLOSE 

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE specifies that 
MAIL$MAILFILE_CLOSE should purge the wastebasket folder when it 
closes the mail file. If the number of bytes deleted by the purge operation 
exceeds a system-defined threshold, MAIL reclaims the deleted space from 
the mail file. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL Utility Routines 
MAIL$MAILFILE_CLOSE 


The system-defined threshold is reserved by Digital. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 


MAIL$_MAILFILE_DATA_RECLAIM 


When you specify MAIL$_ MAILFILE_DATA_ RECLAIM, 
MAIL$MAILFILE_CLOSE returns the number of data buckets reclaimed 
during the reclaim operation as a longword value. 


MAIL$_MAILFILE_DATA_SCAN 


When you specify MAIL$_MAILFILE_DATA_ SCAN, MAIL$MAILFILE_ 
CLOSE returns the number of data buckets scanned during the reclaim 
operation as a longword value. 


MAIL$_MAILFILE_INDEX_RECLAIM 


When you specify MAIL$ MAILFILE_INDEX_RECLAIM, 
MAIL$MAILFILE_ CLOSE returns the number of index buckets reclaimed 
during a reclaim operation as a longword value. 


MAIL$_MAILFILE_MESSAGES DELETED 


When you specify MAIL$_MAILFILE_MESSAGES_DELETED, 
MAIL$MAILFILE_CLOSE returns the number of messages deleted as 
a longword value. 


MAIL$_MAILFILE_TOTAL_RECLAIM 

When you specify MAIL$ MAILFILE_TOTAL_RECLAIM, 
MAIL$MAILFILE_CLOSE returns the number of bytes reclaimed during 
a reclaim operation as a longword value. 





DESCRIPTION 


If you specify the input item code MAIL$_MAILFILE_FULL_CLOSE, this 
procedure purges the wastebasket folder automatically before it closes the 
file. If the number of bytes deleted by this procedure exceeds the deleted 
byte threshold, the system performs a convert/reclaim operation on the 
file. 
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CONDITION 
VALUES SS$_NORMAL 
RETURNED MAIL$_INVITMCOD 


MAIL$_INVITMLEN 
MAIL$_MISREQITEM 
MAIL$_NOFILEOPEN 
SS$_ACCVIO 
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Normal successful completion. 
The specified item code is invalid. 
The specified item length is invalid. 
The required item is missing. 

No mail file is open. 

Access violation. 


MAIL Utility Routines 
MAIL$MAILFILE_COMPRESS 


MAILSMAILFILE_-. COMPRESS 


Compresses a mail file. 





FORMAT 


MAIL$MAILFILE_COMPRESS context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Mail file context information to be passed to various mail file routines. 


The context argument is the address of a longword that contains mail file 
context information returned by MAIL$MAILFILE_BEGIN. 


in_item_list 

VMS usage: itmlst_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$MAILFILE_BEGIN for a description of an input descriptor. 


input Item Codes 


MAIL$_MAILFILE_DEFAULT_NAME 


MAIL$_MAILFILE_DEFAULT_NAME specifies the default file 
specification MAIL should use when opening a mail file. The buffer 
address field points to a character string 0 to 255 characters long that 
defines the default file specification. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 
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If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_COMPRESS uses the current default directory as the 
default mail file specification. 


If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, 
MAIL$MAILFILE_COMPRESS creates the default mail file specification 
from the following sources: 


¢ Disk and directory defined in the caller’s user authorization file (UAF) 
¢ Subdirectory defined in the MAIL user profile 
¢ Default file type of MAI 


MAIL$ MAILFILE_FULL_CLOSE 

The Boolean item code MAIL$ MAILFILE_FULL_CLOSE requests that 
the wastebasket folder be purged and that convert and reclaim operations 
be performed, if necessary. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$_MAILFILE_NAME 


MAIL$_MAILFILE_NAME specifies the name of a mail file to be opened. 
The buffer that the buffer address field points to contains a character 
string of 0 to 255 characters. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


If you do not specify MAIL$_ MAILFILE_NAME, the default mail file name 
is MAIL 


out_item_list 

VMS usage: itmlist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 


MAIL$_MAILFILE_RESULTSPEC 


When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL returns the 
resultant mail file specification. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


AN 


MAIL Utility Routines 
MAIL$MAILFILE_COMPRESS 





DESCRIPTION _eéiIf you do not specify an input file, the MAILS$MAILFILE_COMPRESS 
routine compresses the currently open MAIL file. The MAIL$MAILFILE_ 
COMPRESS routine signals informational messages concerning the phase 
of the compression. 





CONDITION SS$_ NORMAL Normal successful completion. 

VALUES a a ee 
MAIL$_INVITMCOD The specified item code is invalid. 

RETURNED MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
MAIL$_NOTISAM The message file format is not ISAM. 
RMS$_FNF The specified file cannot be found. 
RMS$_SHR The specified file is not shareable. 
SS$_ACCVIO . Access violation. 
SS$_IVDEVNAM The specified device name is invalid. 


Any condition value returned by LIB$FIND_IMAGE_SYMBOL, LIB$RENAME_FILE, 
$CREATE, $OPEN, $PARSE, and $SEARCH. 
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MAILSMAILFILE_END 


Terminates mail file processing. 











FORMAT MAIL$MAILFILE_END context, in_item_list, 
out_item_list 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS _~ context 
VMS usage: context 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 

Mail file context information to be passed to mail file routines. The 
context argument is the address of a longword that contains MAILFILE 
context information returned by MAIL$MAILFILE_BEGIN. 


If mail file processing is terminated successfully, MAIL sets the value of 
the argument context to 0. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$MAILFILE_BEGIN for a description of an input item 
descriptor. 


Input Item Codes 


MAIL$_MAILFILE_FULL_CLOSE 


The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that 
the wastebasket folder be purged and that convert and reclaim operations 
be performed, if necessary. 


MAIL Utility Routines 
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Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 


None. 








DESCRIPTION = The MAIL$MAILFILE_END routine deallocates the mail file context 
created by MAIL$MAILFILE_BEGIN as well as any dynamic memory 
allocated by other mail file processing routines. 

CONDITION 
SS$_ NORMAL Normal successful completion. 

VALUES | ane ay der 

RETURNED MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 

SS$_ACCVIO Access violation. 


Any condition value returned by LIBSFREE_VM. 
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-MAILS$MAILFILE_INFO FILE 


Obtains information about a specified mail file. 





MAIL$MAILFILE_INFO_FILE context, in_item_list, 
out_item_list 





ARGUMENTS 
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VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Mail file context information to be passed to mail file routines. The 


context argument is the address of a longword that contains mail file 
context information returned by MAIL$MAILFILE_BEGIN. 


in_item_list 

VMS usage: itmlst_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$MAILFILE_BEGIN for a description of an input descriptor. 


input Item Codes 


MAIL$_MAILFILE_DEFAULT_NAME 
MAIL$_MAILFILE_DEFAULT_NAME specifies the default mail file 
specification MAIL$MAILFILE_INFO_FILE should use when opening 
a mail file. The buffer address field of the item descriptor points to a 
character string of 0 to 255 characters that defines the default mail file 
specification. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL Utility Routines 
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If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_INFO_FILE uses the current default directory as the 
default mail file specification. 


If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, 
MAIL$MAILFILE_INFO_FILE creates the default mail file specification 
from the following sources: 


¢ Disk and directory defined in the caller’s user authorization file (UAF) 
¢ Subdirectory defined in the MAIL user profile 
¢ Default file type of MAI 


MAIL$_MAILFILE_FOLDER_ROUTINE 


MAIL$_MAILFILE_FOLDER_ROUTINE specifies an entry point longword 
address of a user-written routine that MAIL$MAILFILE_INFO_FILE 
should use to display folder names. MAIL$¢MAILFILE_INFO_FILE calls 
the user-written routine for each folder in the mail file. 


MAIL$_MAILFILE_NAME 

MAIL$ MAILFILE_NAME specifies the name of the mail file to be opened. 
The buffer address field points to a buffer that contains a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


If you do not specify MAIL$_MAIFILE_NAME, the default mail file name 
L. 
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MAIL$ MAILFILE_USER_DATA 

MAIL$ MAILFILE_USER_DATA specifies a longword that 
MAIL$MAILFILE_INFO_FILE should pass to the user-defined folder 
name action routine. 


This item code is valid only when used with the item code MAIL$_ 
MAILFILE_FOLDER_ROUTINE. 


out_item_list 

VMS usage: itmlst_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 


MAIL$_MAILFILE_DELETED_BYTES 


When you specify MAIL$_MAILFILE_DELETED_BYTES, 
MAIL$MAILFILE_INFO_FILE returns the number of deleted bytes in 
a specified mail file as longword value. 
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MAIL$_MAILFILE_RESULTSPEC 


When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_ 
INFO_FILE returns the resultant mail file specification. The buffer 
address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MAILFILE_WASTEBASKET 


When you specify MAIL$_ MAILFILE_WASTEBASKET, 
MAIL$MAILFILE_INFO_FILE returns the name of the wastebasket folder 
of the specified mail file. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 39 characters long. 


Specify a value from 0 to 39 in the buffer length field of the item 
descriptor. 





DESCRIPTION 


If you do not specify an input file, the MAIL$MAILFILE_INFO_FILE 
returns information about the currently open MAIL file. 


Folder Action Routines 


If you use the item code MAIL$ MAILFILE_FOLDER_ROUTINE to 
specify a folder name routine, MAIL$MAILFILE_INFO_FILE passes 
control to a user-specified routine. For example, the folder action routine 
could display folder names. The folder action routine passes a pointer 

to the descriptor of a folder name as well as the user data longword. A 
descriptor of zero length indicates that the MAIL$MAILFILE_INFO_FILE 
routine has displayed all folder names. If you do not specify the item code 
MAIL$_MAILFILE_FOLDER_ROUTINE, MAIL$MAILFILE_INFO_FILE 
does not call any folder action routines. 





CONDITION 
VALUES 
RETURNED 
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MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
MAIL$_NOFILEOPEN The mail file is not open. 

MAIL$_NOTISAM The format of the message file is not ISAM. 
MAIL$_OPENIN MAIL cannot open the file as input. 
SS$_ACCVIO Access violation. 


Any condition value returned by $CLOSE, $OPEN, $PARSE, and $SEARCH. 


MAIL Utility Routines 
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MAIL$MAILFILE_MODIFY 


Modifies the informational record of an ISAM-format mail file. 





FORMAT 


MAILSMAILFILE MODIFY context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Mail File context information to be passed to mail file routines. The 


context argument is the address of a longword that contains mail file 
context information returned by MAIL$MAILFILE_BEGIN. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of an input item 
descriptor. 


Input Item Codes 


MAIL$_MAILFILE_DEFAULT_NAME 


MAIL$ MAILFILE_DEFAULT_NAME specifies the default file 
specification MAIL should use when opening a mail file. The buffer 
address field points to a buffer that contains a character string of 0 to 255 
characters that defines the default mail file specification. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 
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If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_MODIFY uses the current default directory as the 
default mail file specification. 


If you do not specify MAIL$ MAILFILE_DEFAULT_NAME, 
MAIL$MAILFILE_MODIFY creates the default mail file specification 
from the following sources: 


¢ Disk and directory defined in the caller’s user authorization file (UAF) 
e Subdirectory defined in the MAIL user profile 
¢ Default file type of MAI 


MAIL$_MAILFILE_NAME 


MAIL$_MAILFILE_NAME specifies the name of the mail file that MAIL 
should open. The buffer address field points to a buffer that contains a 
character string of 0 to 255 characters. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


If you do not specify MAIL$_MAILFILE_NAME, the default mail file name 
is MAIL. 


MAIL$_MAILFILE_WASTEBASKET_NAME 


MAILFILE_WASTEBASKET_NAME specifies a new folder name for the 
wastebasket in the specified mail file. The buffer address field points to 
a buffer that contains a character string of 1 to 39 characters. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of an output descriptor. 


Output Item Codes 


MAIL$_MAILFILE_RESULTSPEC 

When you specify MAIL$_ MAILFILE_RESULTSPEC, MAIL returns the 
resultant mail file specification. The buffer address field points to a 
buffer that receives a character string from 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 





DESCRIPTION _ Ifa mail file is not specified, the currently open mail file is used. 
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CONDITION 7 ee 

VALUES MAIL$_ILLFOLNAM The eu ee pane ’ neon 
MAIL$_INVITMCOD The specified item code is invalid. 

RETURNED MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
MAIL$_NOTISAM The format of the message file is not ISAM. 
MAIL$_OPENIN MAIL cannot open the file as input. 
SS$_ACCVIO Access violation. 


Any condition value returned by $CLOSE, $FIND, $PUT, and $UPDATE. 
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MAILSMAILFILE_OPEN 


Opens a specified mail file for processing. You must use this routine to open 
a mail file before you can do either of the following: 


¢ Call any mail file routines to manipulate mail files 
« Call message routines to read messages from the specified mail file 








FORMAT MAIL$MAILFILE_OPEN context, in_item_list, 
out_item_list 
RETURNS | VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS ~— context 
VMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
Mail file context information to be passed to mail file routines. The 


context argument is the address of a longword that contains mail file 
context information returned by MAIL$MAILFILE_BEGIN. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of an input item 
descriptor. 


Input Item Codes 


MAIL$_MAILFILE_DEFAULT_NAME 


MAIL$_ MAILFILE_DEFAULT_NAME specifies the default file 
specification MAIL$MAILFILE_OPEN should use when opening a mail 


MAIL-52 


MAIL Utility Routines 
MAIL$MAILFILE_OPEN 


file. The buffer address field points to a character string of 0 to 255 
characters that defines the default file specification. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_OPEN uses the current default directory as the default 
mail file specification. 


If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, 
MAIL$MAILFILE_OPEN creates the default mail file specification from 
the following sources: 


¢ Disk and directory defined in the caller’s user authorization file (UAF) 
e Subdirectory defined in the MAIL user profile 
¢ Default file type of MAI 


MAIL$_MAILFILE_NAME 


MAIL$_MAILFILE_NAME specifies the name of the mail file 
MAIL$MAILFILE_OPEN should open. The buffer address field points to 
a buffer that contains a character string of 0 to 255 characters. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


If you do not MAIL$_MAILFILE_NAME, the default mail file name is 
MAIL. 


out_item_list 

VMS usage: itmlist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 


MAIL$_MAILFILE_DELETED_BYTES 

When you specify MAIL$ MAILFILE_DELETED_BYTES, 
MAIL$MAILFILE_OPEN returns the number of deleted bytes in the 
specified mail file as a longword value. 


MAIL$_MAILFILE_INDEXED 

When you specify MAIL$_MAILFILE_INDEXED, MAIL$MAILFILE_ 
OPEN returns a Boolean TRUE if the opened mail file format is ISAM. 
The buffer length field points to a longword that receives the Boolean 
value. 
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MAIL$_MAILFILE_RESULTSPEC 


When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_ 
OPEN returns the resultant mail file specification. The buffer address 
field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_ MAILFILE_WASTEBASKET 

When you specify MAIL$_ MAILFILE_WASTEBASKET, 
MAIL$MAILFILE_OPEN returns the name of the wastebasket for the 
specified mail file. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 








DESCRIPTION _ The default mail file specification is MAIL.MAI in the mail subdirectory. 
CONDITION Seas 
MAIL$_FILEOPEN The mail file is already open. 
VALUES er oe edt 
RETURNED MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
MAIL$_NOMSGS No messages are available. 
SS$_ACCVIO Access violation. 
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Any condition value returned by LIBSGET_VM and $CONNECT, and $OPEN. 
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MAIL$MAILFILE_PURGE_WASTE 


Deletes messages contained in the wastebasket folder of the currently open 
mail file. 





FORMAT 


MAIL$MAILFILE_PURGE_WASTE context, 
in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Mail file context information to be passed to other mail file routines. The 
context argument is the address of a longword that contains mail file 
context information. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 

See MAIL$MAILFILE_BEGIN for a description of an input item 
descriptor. 

input Item Codes 


MAIL$_MAILFILE_RECLAIM 


The Boolean item code MAIL$_ MAILFILE_RECLAIM specifies that 
MAIL$MAILFILE_PURGE_WASTE purge the wastebasket folder and 
reclaim deleted space in the mail file. 


Specify the value 0 in the buffer length field of the item descriptor. 
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MAIL$_MAILFILE_RECLAIM explicitly requests a reclaim operation and 
overrides the deleted bytes threshold regardless of the number of deleted 
bytes during a mail file purge operation. 


out_item_list 

VMS usage: itmlst_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MAILFILE_BEGIN for a description of a output itera 
descriptor. 


Output Item Codes 


MAIL$_MAILFILE_DATA_RECLAIM 

When you specify MAIL$_MAILFILE_DATA_RECLAIM, 
MAIL$MAILFILE_PURGE_WASTE returns the number of data buckets 
reclaimed during the reclaim operation as a longword value. 


MAIL$_MAILFILE_DATA_SCAN 


When you specify MAIL$_MAILFILE_DATA_ SCAN, MAIL$MAILFILE_ 
PURGE_WASTE returns the number of data buckets scanned during the 
reclaim operation as a longword value. 


MAIL$_MAILFILE_INDEX_RECLAIM 


When you specify MAIL$_MAILFILE_INDEX_RECLAIM, MAIL returns 
the number of index buckets reclaimed during a reclaim operation as a 
longword value. 


MAIL$_MAILFILE_DELETED_BYTES 


When you specify MAIL$ MAILFILE_DELETED_BYTES, 
MAIL$MAILFILE_PURGE_WASTE returns the number of bytes deleted 
from the mail file as a longword value. 


MAIL$_MAILFILE_ MESSAGES DELETED 

When you specify MAIL$_MAILFILE_MESSAGES_DELETED, 
MAIL$MAILFILE_PURGE_WASTE returns the number of deleted 
messages as a longword value. 


MAIL$_MAILFILE_TOTAL_RECLAIM 

When you specify MAIL$_ MAILFILE_TOTAL_RECLAIM, 
MAIL$MAILFILE_PURGE_WASTE returns the number of bytes reclaimed 
due to a reclaim operation as a longword value. 





DESCRIPTION __ If you specify the MAIL$_MAILFILE_RECLAIM item descriptor, all the 
. bytes deleted from the mail file by this routine are reclaimed. 
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CONDITION 
VALUES 
RETURNED 


MAIL$_NORMAL 
MAIL$_INVITMCOD 
MAIL$_INVITMLEN 
MAIL$_MISREQITEM 
MAIL$_NOFILEOPEN 
MAIL$_NOTISAM 
SS$_ACCVIO 


Normal successful completion. 

The specified item code is invalid. 
The specified item length is invalid. 
The required item is missing. 

No mail file is currently open. 

The message file format is not ISAM. 
Access violation. 
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MAIL$MESSAGE_BEGIN 


Begins message processing. You must call this routine before calling any 
other message routines. 





FORMAT 


MAIL$MESSAGE BEGIN context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Message context information to be passed to various message routines. 
The context argument is the address of a longword that contains message 
context information. 


You should specify the value of this argument as 0 in the first of a 
sequence of calls to message routines. In following calls, you should 
specify the message context value returned by this routine. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
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The following diagram depicts the format of a single item descriptor: 


31 15 0 
Buffer Address 


Return Length Address 


ZK-1705-GE 










in_item_list Item Descriptor Fields 


buffer length 


A word specifying the length (in bytes) of the buffer that supplies the 
information needed by the routine to process the specified item code. The 
required length of the buffer depends on the item code specified in the 
item code field of the item descriptor. If the value of buffer length is too 
small, the routine truncates the data. 


item code 


A word containing a user-supplied symbolic code that specifies an option 
for the MAIL operation. These codes are defined by the $MAILDEF macro. 
See Input Item Codes for a description of these codes. 


buffer address 
A longword containing the address of the buffer that supplies information 
to the routine. 


return length address 
This field is not used. 


MAIL$MESSAGE_BEGIN Input Item Codes 


MAIL$_MESSAGE_FILE_CTX 

MAIL$_MESSAGE_FILE_CTX specifies the mail file context received 
from MAIL$MAILFILE_BEGIN to be passed to the message routines. 
The buffer address field of the item descriptor points to a longword that 
contains mail file context information. 


The item code MAIL$_MESSAGE_FILE_CTX is required. 


out_item_list 

VMS usage: itmlst_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 
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The following diagram depicts the format of a single item descriptor: 
31 


15 0 
Buffer Address 
Return Length Address 
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Out_item_list Item Descriptor Fields 


buffer length 

A word containing a user-supplied integer specifying the length (in bytes) 
of the buffer in which the routine is to write the information. The length 
of the buffer needed depends on the item code specified in the item code 
field of the item descriptor. If the value of buffer length is too small, the 
routine truncates the data. 


item code 


A word containing a user-supplied symbolic code specifying the item of 
information that the routine is to return. These codes are defined by 
the $MAILDEF macro. See Output Item Codes for a description of these 
codes. 


buffer address 


A longword containing the user-supplied address of the buffer in which the 
routine is to write the information. 


return length address 


A longword containing the user-supplied address of a word in which the 
routine writes the actual length in bytes of the information it returned. 


Output Item Codes 


MAIL$_MESSAGE_SELECTED | 


When you specify MAIL$_. MESSAGE_SELECTED, MAIL$MESSAGE_ 
BEGIN returns the number of messages selected (from sequential mail 
files only) as a longword value. 





DESCRIPTION MAIL$MESSAGE_BEGIN creates and initializes a message context for 
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CONDITION MAIL$_ILLCTXADR The context block address is illegal. 

VALUES ae tee 
MAIL$_INVITMCOD The specified item code is invalid. 

RETURNED MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
MAIL$_NOFILEOPEN The mail file is not open. 
MAIL$_WRONGCTX The context block is incorrect. 
MAIL$_WRONGFILE The specified file is incorrect in this context. 
SS$_ACCVIO Access violation. 


_ Any condition value returned by $GET and LIB$GET_VM. 
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MAIL$MESSAGE_COPY 


Copies messages between files or folders. 





FORMAT 


MAIL$MESSAGE_COPY context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Message context information to be passed to message routines. The 


context argument is the address of a longword that contains message 
context information returned by MAIL$SMESSAGE_BEGIN. 


You should specify this argument as 0 in the first of a sequence of calls 
to message routines. In following calls, you should specify the message 
context value returned by the previous routine. 


in_item_list 

VMS usage: itmlist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an input item 
descriptor. 


Input Item Codes 


MAIL$_MESSAGE_BACK 


When you specify the Boolean item code MAIL$_MESSAGE_BACK, 
MAIL$MESSAGE_COPY copies the message preceding the current 
message. 
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Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and 
MAIL$_MESSAGE_NEXT in the same call to MAILSMESSAGE_COPY. 


MAIL$_MESSAGE_DEFAULT_NAME 


MAIL$_ MESSAGE_DEFAULT_NAME specifies the default file 
specification of a mail file to open in order to copy a message. The buffer 
address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_DELETE 

When you specify the Boolean item code MAIL$_MESSAGE_DELETE, 
MAIL$MESSAGE_COPY deletes the message in the current folder after 
the message has been copied to a destination folder. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Specify MAIL$_MESSAGE_DELETE to emulate the operation of MAIL 
MOVE or FILE command. 


MAIL$_MESSAGE_FILE_ACTION 


MAIL$ MESSAGE_FILE_ACTION specifies the address of the mail file 
action routine called if a mail file is to be created. Two parameters are 
passed as follows: 


e User data longword 


e Address of the descriptor of the file name to be created 


The buffer address field of the item descriptor points to a longword that 
denotes a procedure entry mask. 


MAIL$_MESSAGE_FILENAME 


MAIL$ MESSAGE_FILENAME specifies the name of the mail file to 
which the current message will be moved. The buffer address field of the 
item descriptor points to a buffer that contains a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. : 


MAIL$_MESSAGE_FOLDER 

MAIL$ MESSAGE_FOLDER specifies the name of the target folder for 
moving mail messages. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


The item code MAIL$_MESSAGE_FOLDER is required. 
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MAIL$_MESSAGE_FOLDER_ACTION 


MAIL$ MESSAGE_FOLDER_ACTION specifies the entry point address of 
the folder action routine called if a folder is to be created. Two parameters 
are passed as follows: 


e User data longword 


e¢ Address of a descriptor of the folder name to be created. 


The buffer address field of the item descriptor points to a longword that 
specifies a procedure entry mask. 


MAIL$_MESSAGE_ID 

MAIL$_MESSAGE_ID specifies the message identification number of the 
message on which the operation is to be performed. The buffer address 
field of the item descriptor points to a longword that contains the message 
identification number. 


Do not specify MAIL$_MESSAGE_BACK, MAIL$_ MESSAGE_ID, and 
MAIL$_MESSAGE_ NEXT in the same call to MAIL$MESSAGE_COPY. 


MAIL$_MESSAGE_NEXT 


When you specify the Boolean item code MAIL$_ MESSAGE_NEXT, MAIL 
copies the message following the current message. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Do not specify MAIL$_ MESSAGE_BACK, MAIL$_MESSAGE_ID, and 
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY. 


MAIL$_MESSAGE_USER_DATA 

MAIL$_MESSAGE_USER_DATA specifies data passed to the folder 
action and mail file action routines. The buffer address field of the 
item descriptor points to a user data longword. 


Specify MAIL$_ MESSAGE_USER_DATA with the item codes MAIL$_ 
MESSAGE_FILE_ACTION and MAIL$ MESSAGE_FOLDER_ACTION 
only. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an output item 
descriptor. 
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Output Item Codes 


MAIL$_MESSAGE_FILE_CREATED 


When you specify the Boolean item code MAIL$_MESSAGE_FILE_ 
CREATED, MAIL$MESSAGE_COPY returns the value of the file created 
flag as longword value. 


MAIL$_MESSAGE_FOLDER_CREATED 


When you specify the Boolean item code MAIL$_ MESSAGE_FOLDER_ 
CREATED, MAIL$MESSAGE_COPY returns the value of the folder 
created flag as a longword value. 


MAIL$_MESSAGE_RESULTSPEC 


When you specify MAIL$_ MESSAGE_RESULTSPEC, MAIL$MESSAGE_ 
COPY returns the mail file resultant file specification. The buffer 
address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 








DESCRIPTION __ Ifyou do not specify a file name, the routine copies the message to another 
folder in the currently open mail file. The target mail file must be an 
ISAM-format file. 

CONDITION 
SS$_NORMAL Normal successful completion. 

VALUES 

RETURNED MAIL$_MSGINFO Informational records are successully returned. 
MAIL$_MSGTEXT Text record is successfully returned. - 
MAIL$_BADVALUE The specified keyword value is invalid. 
MAIL$_CONITMCOD The specified item codes define conflicting operations. 
MAIL$_DATIMUSED The date and time is currently used in the specified 

file. 
MAIL$_DELMSG The message is deleted. 
MAIL$_ILLCTXADR The context block address is illegal. 
MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM ~ The required item is missing. 
MAIL$_NOFILEOPEN The mail file is not open. 
MAIL$_NOMOREREC No more records can be found. 
MAIL$_NOTREADIN The operation is invalid; you are not reading a 
message. 
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MAIL$_RECTOBIG The record is too large for the MAIL buffer. 
MAIL$_WRONGCTX The context block is incorrect. 

MAIL$_WRONGFILE The specified file is incorrect in this context. 
SS$_IVDEVNAM The device name is invalid. 

SS$_ACCVIO Access violation. 

as ic value returned by $CONNECT, $CREATE, $OPEN, $WRITE, $READ, 
an . 
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MAIL$MESSAGE_DELETE 


Deletes a specified message from the currently selected folder. 





FORMAT 


MAIL$MESSAGE_DELETE context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Message context information to be passed to message routines. The 
context argument is the address of a longword that contains message 
context information. 


in_item_list 

VMS usage: itmist_3 

type: ~ longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 

See MAIL$MESSAGE_BEGIN for a description of an input item 
descriptor. 

Input Item Codes 


MAIL$ MESSAGE _ID 

MAIL$ MESSAGE_ID specifies the message identification number of the 
message on which the operation is to be performed. The buffer address 
field points to a longword that contains the message identification number. 


The item code MAIL$_MESSAGE_ID is required. 
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out_item_list 

VMS usage: itmlist_3 

type: longword 

access: write only 

mechanism: by reference . 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 


None. 








DESCRIPTION When you delete a message from a selected folder, it is moved to the 
wastebasket folder. You cannot delete a message from the wastebasket 
folder. You must use the MAILSMESSAGE_PURGE_WASTE routine to 
empty the wastebasket folder. 

CONDITION . 

VALUES SS$NORMAL Normal successful completion. 

RETURNED MAIL$_ILLCTXADR The context block address is illegal. 
MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
MAIL$_NOFILEOPEN The mail file is not open. 

MAIL$_WRONGCTX The context block is incorrect. 
MAIL$_WRONGFILE The specified file is incorrect in this context. 
SS$_ACCVIO Access violation. 
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MAIL$MESSAGE END 


Ends message processing. 





FORMAT 


MAILSMESSAGE_END context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Message context information to be passed to message routines. The 
context argument is the address of a longword that contains message 
context information returned by MAIL$MESSAGE_BEGIN. If message 
processing ends successfully, the argument context is changed to 0. 


in_item_list 

VMS usage: itmlist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an input item 
descriptor. 


Input Item Codes 


None. 
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out_ltem_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 
None. 





DESCRIPTION The MAIL$MESSAGE_END routine deallocates the message context 
created by MAIL$MESSAGE_BEGIN as well as any dynamic memory 
allocated by other message routines. 





CONDITION — a 
MAIL$_INVITMCOD The specified item code is invalid. 

VALUES oe seahsi: 

RETURNED MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
SS$_ACCVIO Access violation. 


Any condition value returned by LIBSFREE_VM. 
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MAIL$MESSAGE_GET 


Retrieves a message from the set of currently selected messages. 





FORMAT 


MAIL$MESSAGE_GET context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Message context information to be passed to message routines. The © 
context argument is the address of a longword that contains message 
context information returned by MAIL$MESSAGE_BEGIN. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$MESSAGE_BEGIN for a description of an input item 
descriptor. 


input item Codes 


MAIL$_MESSAGE_AUTO_NEWMAIL 

When you specify the Boolean item code MAIL$_ MESSAGE_AUTO_ 
NEWMAIL, MAIL$MESSAGE_GET places a new message in the MAIL 
folder as it is read automatically. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 
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MAIL$ MESSAGE_BACK 

When you specify the Boolean item code MAIL$_MESSAGE_BACK, 
MAIL$MESSAGE_GET reads the message identification number of a 
specified message to return the first record of the preceding message. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Do not specify the item codes MAIL$ MESSAGE_BACK, MAIL$_ 
MESSAGE_CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_ 
NEXT in the same call to MAIL$S¢MESSAGE_GET. 


MAIL$ MESSAGE_CONTINUE 

When you specify the Boolean item code MAIL$¢_MESSAGE_CONTINUE, 
MAIL$MESSAGE_GET reads the message identification number of a 
specified message to return the next text record of the current message. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Do not specify the item codes MAIL$ MESSAGE_BACK, MAIL$_ 
MESSAGE_CONTINUE, MAIL$_ MESSAGE_ID, and MAIL$_MESSAGE_ 
NEXT in the same call to MAIL$MESSAGE_GET. 


MAIL$_MESSAGE_ID 

MAIL$ MESSAGE_ID specifies the message identification number of a 
message on which an operation is to be performed. The buffer address 
field of the item descriptor points to a longword that contains the message 
identification number. 


Do not specify the item codes MAIL$_ MESSAGE_BACK, MAIL$_ 
MESSAGE_CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_ 
NEXT in the same call to MAILSMESSAGE_GET. 


MAIL$_MESSAGE_NEXT 

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, 
MAIL$MESSAGE_GET reads the message identification number of a 
specified message to return the first record of the message following the. 
current message. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_ 
MESSAGE_CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_ 
NEXT in the same call to MAILSMESSAGE_GET. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an output item 
descriptor. 


MAIL Utility Routines 
MAIL$MESSAGE_GET 


Output Item Codes 


MAIL$_MESSAGE_BINARY_DATE 
When you specify MAIL$_ MESSAGE_BINARY_DATE, MAIL$MESSAGE_ 


GET returns the message arrival date as a quadword binary value. 


MAIL$_MESSAGE_CC 

When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_GET returns 
the CC: field of the current message. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_CURRENT_ID 

When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_ 
GET returns the message identification number of the current message. 
The buffer address field of the item descriptor points to a longword that 
receives the message identifier number. 


MAIL$ MESSAGE_DATE 

When you specify MAIL$_ MESSAGE_DATE, MAIL$SMESSAGE_GET 
returns the message creation date string. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_ MESSAGE _EXTID 

MAIL$MESSAGE_EXTID specifies the external message identification 
number of the current message. The buffer address field of the item 
descriptor points to a buffer that contains a character string 0 to 255 
characters long. 


MAIL$_MESSAGE_FROM 

When you specify MAIL$_ MESAGE_FROM, MAIL$MESSAGE_GET 
returns the From: field of the specified message. The buffer address 
field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$ MESSAGE RECORD 

When you specify MAIL$_MESSAGE_RECORD, MAIL$MESSAGE_GET 
returns a record of the message. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_RECORD is valid only when specified with the item 
code MAIL$_MESSAGE_CONTINUE. 
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Do not specify MAIL$ MESSAGE_RECORD with the following item codes: 
¢ MAIL$ MESSAGE_BACK 

¢ MAIL$ MESSAGE_ID 

¢ MAIL$ MESSAGE_NEXT 


MAIL$ MESSAGE_RECORD_TYPE 

When you specify MAIL$ MESSAGE_RECORD_TYPE, 
MAIL$MESSAGE_GET returns the record type. A record may be either 
header information (MAIL$ MESSAGE_HEADER) or text (MAIL$_ 
MESSAGE_TEXT). The buffer address field of the item descriptor points 
to a word that receives the record type. 


MAIL$_MESSAGE_RETURN_FLAGS 

When you specify MAIL$_ MESSAGE_RETURN_FLAGS, 
MAIL$MESSAGE_GET returns the MAIL system flag for the current 
message as a 2-byte bitmask value. 


MAIL$_MESSAGE_SENDER 

When you specify MAIL$_ MESSAGE_SENDER, MAIL$MESSAGE_GET 
returns the name of the sender of the current message. The buffer 
address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_SIZE 
When you specify MAIL$_ MESSAGE_SIZE, MAIL$MESSAGE_GET 
returns the size in records of the current message as a longword value. 


MAIL$ MESSAGE_SUBJECT 

When you specify MAIL$¢_ MESSAGE_SUBJECT, MAIL$MESSAGE_GET 
returns the Subject: field of the specified message. The buffer address 
field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$ MESSAGE_TO 

When you specify MAIL$_MESSAGE_TO, MAIL$SMESSAGE_GET returns 
the To: field of the specified message. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 





DESCRIPTION 
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The first time the MAIL$MESSAGE_GET routine is called, the message 
information is returned for the first requested message, and the status 
returned is MAIL$_ MSGINFO. Subsequent calls to MAILSMESSAGE_ 
GET with the MAIL$_ MESSAGE_CONTINUE item code return the 
message text records with the status MAIL$_ MSGTEXT, until no more 
records are left, when MAIL$_ NOMOREREC is returned. 
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CONDITION 
VALUES 
RETURNED 


MAIL$_MSGINFO 
MAIL$_MSGTEXT 
MAIL$_iILLCTXADR 
MAIL$_INVITMCOD 
MAIL$_INVITMLEN 
MAIL$_MISREQITEM 
MAIL$_NOFILEOPEN 
MAIL$_NOMOREREC 
MAIL$_NOTREADIN 


MAIL$_RECTOBIG 
MAIL$_WRONGCTX 
MAIL$_WRONGFILE 
SS$_ACCVIO 


Informational records are successully returned. 
Text record is successfully returned. 

The context block address is illegal. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 

The mail file is not open. 

No more records can be found. 


The operation is invalid; you are not reading a 
message. 


The record is too large for the MAIL buffer. 
The context block is incorrect. 

The specified file is incorrect in this context. 
Access violation. 


Any condition value returned by $FIND and $UPDATE. 
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MAILS$MESSAGE_INFO 


Obtains information about a specified message contained in the set of 
currently selected messages. 





FORMAT 


MAIL$MESSAGE_INFO context, in_item_list, 
out_item_lIist 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Message context information to be passed to message routines. The 


context argument is the address of a longword that contains message 
context information returned by MAILSMESSAGE_BEGIN. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$MESSAGE_BEGIN for a description of an input descriptor. 


Input Item Codes 


MAIL$_MESSAGE_BACK 


When you specify Boolean item code MAIL$_MESSAGE_BACK, 
MAIL$MESSAGE_INFO reads the message identification number of the 
current message and returns the message preceding the current message. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 
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Do not specify MAIL$ MESSAGE_BACK,MAIL$_MESSAGE_ID, and 
MAIL$_ MESSAGE_NEXT in the same call to MAIL$MESSAGE_INFO. 


MAIL$_MESSAGE_ID 

MAIL$_MESSAGE_ID specifies the message identification number of the 
message on which the operation is to be performed. The buffer address 
field of the item descriptor points to a longword that contains the message 
identification number. 


Do not specify MAIL$_MESSAGE_BACK,MAIL$ MESSAGE_ID, and 
MAIL$_MESSAGE_NEXT in the same call to MAILSMESSAGE_INFO. 


MAIL$_MESSAGE_NEXT 

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, 
MAIL$MESSAGE_INFO reads the message identification number of 
the current message and returns the message that follows it. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Do not specify MAIL$ MESSAGE_BACK,MAIL$_MESSAGE_ID, and 
MAIL$ MESSAGE_NEXT in the same call to MAIL$¢MESSAGE_INFO. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 


MAIL$ MESSAGE_BINARY_DATE 
When you specify MAIL$_ MESSAGE_BINARY_DATE, MAIL$MESSAGE_ 
INFO returns the message arrival date as a quadword binary value. 


MAIL$_MESSAGE_CC 

When you specify MAIL$ MESSAGE_CC, MAIL$MESSAGE_INFO 
returns the CC: field of the current message. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 
255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_CURRENT_ID 

When you specify MAIL$_ MESSAGE_ID, MAILSMESSAGE_INFO returns 
the message identification number of the current message. The buffer 
address field of the item descriptor points to a longword that receives the 
message identification number of the current message. 
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MAIL$_MESSAGE_DATE 

When you specify MAIL$_ MESSAGE_DATE, MAIL$MESSAGE_INFO 
returns the message creation date string. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. . 


MAIL$_MESSAGE_EXTID 

When you specify MAIL$_MESSAGE_EXTID, MAIL$MESSAGE_INFO 
returns the external identification number of the current message as a 
string. The buffer address field of the item descriptor points to a buffer 
that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$ MESSAGE_FROM 

When you specify MAIL$_ MESSAGE_FROM, MAIL$MESSAGE_INFO 
returns the From: field of the specified message. The buffer address 
field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_REPLY_PATH 


When you specify MAIL$_MESSAGE_REPLY_PATH, MAIL$MESSAGE_ 
INFO returns the reply path of the specified message. The buffer 
address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_RETURN_FLAGS 

When you specify MAIL$_ MESSAGE_RETURN_FLAGS, 
MAIL$MESSAGE_INFO returns the MAIL system flag values for the 
current message as a 2-byte bitvector value. 


MAIL$ _MESSAGE_SENDER 

When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_INFO 
returns the name of the sender of the current message. The buffer 
address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_SIZE 


When you specify MAIL$_MESSAGE_SIZE, MAIL$SMESSAGE_INFO 
returns the size of the current message in records as a longword value. 
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MAIL$ MESSAGE_SUBJECT 

When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_INFO 
returns the Subject: field of the specified message. The buffer address 
field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_TO 

When you specify MAIL$ MESSAGE_TO, MAIL$MESSAGE_INFO 
returns the To: field of the specified message. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 
255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 








DESCRIPTION MAIL$MESSAGE_INFO and MAIL$MESSAGE_GET perform the same 
function. MAIL$MESSAGE_INFO returns information about messages 
faster than MAIL$MESSAGE_GET; however, MAIL$MESSAGE_INFO 
does not return the actual text of the messages. 

CONDITION Satie . ae . 
MAIL$_CONITMCOD The specified item codes define conflicting operations. 

VALUES 

RETURNED MAIL$_DELMSG The message is deleted. 

MAIL$_ILLCTXADR The context block address is illegal. 
MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
MAIL$_NOFILEOPEN The mail file is not open. 
MAIL$_NOMOREMSG No more messages. 

MAIL$_WRONGCTX The context block is incorrect. 
MAIL$_WRONGFILE The specified file is incorrect in this context. 
$$$ _ACCVIO Access violation. 


Any condition value returned by LIBSGET_VM. 
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MAIL$MESSAGE_MODIFY 


Modifies message information. 





FORMAT 


MAILSMESSAGE MODIFY context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Message context information to be passed to message routines. The 


context argument is the address of a longword that contains message 
context information returned by MAIL$¢MESSAGE_BEGIN. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an input item 
descriptor. 


Input Item Codes 


MAIL$_MESSAGE_BACK 


When you specify the Boolean item code MAIL$_ MESSAGE_BACK, 
MAIL$MESSAGE_MODIFY reads the message identification number of 
the specified message in order to return the first record in the preceding 
message. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 
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Do not specify the item codes MAIL$ MESSAGE_BACK, MAIL$_ 
MESSAGE_ID, and MAIL$ MESSAGE_NEXT in the same call to 
MAIL$MESSAGE_MODIFY. 


MAIL$ MESSAGE_FLAGS 

MAIL$_MESSAGE_FLAGS specifies system flags for new mail. The 
buffer address field of the item descriptor points to a word that contains 
bitvector offsets. The following offsets can be used to modify the 2-byte 
bitvector: 


¢ MAIL$V_REPLIED 
¢ MAIL$V_MARKED 


MAIL$_MESSAGE_ID 

MAIL$ MESSAGE_ID specifies the message identification number of the 
message on which an operation is to be performed. The buffer address 
field of the item descriptor points to a longword that contains the message 
identification number. 


Do not specify the item codes MAIL$ MESSAGE BACK, MAIL$_ 
MESSAGE_ID, and MAIL$ MESSAGE NEXT in the same call to 
MAIL$MESSAGE_ MODIFY. 


MAIL$_MESSAGE_NEXT 

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, 
MAIL$MESSAGE_NEXT reads the message identification number of a 
message and returns the first record in the message following the current 
message. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Do not specify the item codes MAIL$ MESSAGE_BACK, MAIL$_ 
MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to 
MAIL$MESSAGE_MODIFY. 


out_item_list 

VMS usage: itmlist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors i is 
terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 


MAIL$_MESSAGE_CURRENT_ID 

When you specify MAIL$_ MESSAGE_CURRENT_ID, MAIL$MESSAGE_ 
MODIFY returns the message identification number of the current 
message. The buffer address field of the item descriptor points to a 
longword that receives the message identification number. 
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CONDITION 
VALUES 
RETURNED 
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MAIL$_CONITMCOD 
MAIL$_DELMSG 
MAIL$_ILLCTXADR 
MAIL$_INVITMCOD 
MAIL$_INVITMLEN 
MAIL$_MISREQITEM 
MAIL$_NOFILEOPEN 
MAIL$_NOMOREMSG 
MAIL$_WRONGCTX 
MAIL$_WRONGFILE 
SS$_ACCVIO 


The specified item codes define conflicting operations. 
The message is deleted. 

The context block address is illegal. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 

The mail file is not open. 

No more messages. 

The context block is incorrect. 

The specified file is incorrect in this context. 
Access violation. 


Any condition value returned by $FIND and $UPDATE. 
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MAIL$MESSAGE_SELECT 


Selects a message or messages from the currently open mail file. Before you 
attempt to read a message, you must select it. 





FORMAT 


MAIL$MESSAGE_ SELECT context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Message context information to be passed to message routines. The 
context argument is the address of a longword that contains message 
context information returned by MAIL$MESSAGE_BEGIN. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an input item 
descriptor. 


Input Item Codes 


MAIL$_MESSAGE_BEFORE 

When you specify MAIL$_ MESSAGE_BEFORE, MAIL$MESSAGE_ 
SELECT selects a message received before a specified date and time. 
The buffer address field of the item descriptor points to a buffer that 
contains a character string 0 to 255 characters long in absolute time. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 
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MAIL$_MESSAGE_CC_SUBSTRING 


MAIL$ MESSAGE_CC_SUBSTRING specifies a character string that 
must match a substring contained in the CC: field of the specified message. 
If the strings match, the message is selected. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 
255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_FLAGS 


MAIL$ MESSAGE_FLAGS specifies bit masks that must be initialized 
to 1. 


MAIL$ MESSAGE_FLAGS MBZ 
MAIL$ MESSAGE_FLAGS_MBZ specifies MAIL system flags that must 
be set to 0. 


MAIL$_MESSAGE_FOLDER 


MAIL$_MESSAGE_FOLDER specifies the name of the folder that contains 
messages to be selected. 


The buffer address field of the item descriptor points to a buffer that 
contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


This item code is required. 


MAIL$_MESSAGE_FROM_SUBSTRING 

MAIL$_ MESSAGE_FROM_SUBSTRING specifies a user-specified 
character string that must match the substring contained in the From: 
field of a specified message. If the strings match, the message is selected. 


The buffer address field of the item descriptor points to a buffer that 
receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_SINCE 
When you specify MAIL$_MESSAGE_SINCE, MAIL selects a message 
received since a specified date and time. 


The buffer address field of the item descriptor points to a buffer that 
contains a character string 0 to 255 characters long in absolute time. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_TO_SUBSTRING 


MAIL$_MESSAGE_TO_SUBSTRING specifies a user-specified character 
string that must match a substring contained in the To: field of a specified 
message. If the strings match, the message is selected. 


The buffer address field of the item descriptor points to a buffer that 
contains a character string 0 to 255 characters long. 
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Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_MESSAGE_SUBJ_SUBSTRING 


MAIL$_MESSAGE_SUBJ_SUBSTRING specifies a user-specified 
character string that must match a substring contained in the Subject: 
field of a specified message. If the strings match, the message is selected. 


The buffer address field of the item descriptor points to a buffer that 
contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


out_item_list 

VMS usage: itmlist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$MESSAGE_BEGIN for a description of an output item 
descriptor. 


Output Item Codes 


MAIL$_MESSAGE_SELECTED 


When you specify MAIL$_ MESSAGE_SELECTED, MAIL$MESSAGE_ 
SELECT returns the number of selected messages as a longword value. 





DESCRIPTION MAIL$MESSAGE_SELECT deselects previously selected messages 


whether or not you request a valid selection. 





CONDITION 
VALUES 
RETURNED 


MAIL$_ILLCTXADR The context block address is illegal. 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_INVQUAVAL The specified qualifier is invalid 

MAIL$_MISREQITEM The required item is missing. 

MAIL$_NOFILEOPEN ° The mail file is not open. 

MAIL$_NOTEXIST The specified folder does not exist. 

MAIL$_NOTISAM The operation cannot be performed on a non-ISAM 
file. 


MAIL-—85 


MAIL Utility Routines 
MAIL$MESSAGE_SELECT 


MAIL$_WRONGCTX The context block is incorrect. 
MAIL$_WRONGFILE The specified file is incorrect in this context. 
SS$_ACCVIO Access violation. 


Any condition value returned by LIB$GET_VM. 
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MAIL$SEND_ABORT 


Cancels a currently executing send operation. 











FORMAT MAIL$SEND_ABORT context, in_item_list, 
out_item_list 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS __ context 
VMS usage: context 
type: longword (unsigned) 
access: modify 


mechanism: by reference 

Send context information to be passed to send routines. The context 
argument is the address of a longword that contains send context 
information returned by MAIL$SEND_BEGIN. 


in_item_list 

VMS usage: itmlist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$SEND_BEGIN for a description of an input item descriptor. 
Input Item Codes 


None. 
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out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$SEND_BEGIN for a description of an output item descriptor. 
Output Item Codes 
None. 





DESCRIPTION MAIL$SEND_ABORT is useful when, for example, the user enters the key 
sequence Ctrl/c during the execution of MAIL$SEND_MESSSAGE. 





CONDITION 


SS$NORMAL Normal successful completion. 
VALUES ? 


RETURNED 
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MAIL$SEND_ADD_ADDRESS 


Adds an address to the address list. If an address list does not exist, 
MAIL$SEND_ADD_ADDRESS creates one. 





FORMAT 


MAIL$SEND_ADD_ADDRESS context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: ‘longword (unsigned) 

access: modify 

mechanism: by reference 

Send context information to be passed to send routines. The context 
argument is the address of a longword that contains send context 
information returned by MAIL$SEND_BEGIN. 


in_item_list 

VMS usage: itmlist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$SEND_BEGIN for a description of an input item descriptor. 


Input Item Codes 


MAIL$_SEND_USERNAME 


MAIL$_SEND_USERNAME specifies that MAIL add a specified username 
to the address list. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


The item code MAIL$_SEND_USERNAME is required. 
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Note: 


MAIL$_SEND_USERNAME_TYPE 


MAIL$_SEND_USERNAME_TYPE specifies the type of username added 
to the address list. The buffer address field of the item descriptor points 
to a word that contains the username type. 


There are two types of usernames, as follows: 
e Username specified as a Jo: address (default) 


e Username specified as a CC: address 


Currently, the symbols MAIL$_TO and MAIL$_CC define username 
types. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$SEND_BEGIN for a description of an output item descriptor. 
Output Item Codes 


None. 








DESCRIPTION __ If you do not specify a MAIL$_ SEND_USERNAME_TYPE, MAIL$SEND_ 
ADD_ADDRESS uses MAIL$_TO. You can specify only one username per 
call to MAIL$SEND_ADD_ADDRESS. 

CONDITION cee ee a 
MAIL$_INVITMCOD The specified item code is invalid. 

VALUES ce ae 

RETURNED MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 

SS$_ACCVIO Access violation. 
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Any condition values returned by LIBSTPARSE. 
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MAIL$SEND ADD ATTRIBUTE 


Adds an attribute to the message you are currently constructing. 





FORMAT 


MAIL$SEND_ADD_ATTRIBUTE context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Send context information to be passed to send routines. The context 
argument is the address of a longword that contains send context 
information returned by MAIL$SEND_BEGIN. 


You should specify this argument as 0 in the first of a sequence of calls to 
MAIL routines. In following calls, you should specify the SEND context 
value returned by the previous routine. 


in_item_list | 

VMS usage: itmist_3 . 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$SEND_BEGIN for a description of an input item descriptor. 


Input Item Codes 


MAIL$_SEND_CC LINE 

MAIL$_SEND_CC_LINE specifies a descriptor of the CC: field text. The 
buffer address field of the item descriptor points to a buffer that contains 
a character string 0 to 255 characters long. 
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Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_SEND_FROM_LINE 


MAIL$_SEND_FROM_LINE specifies a descriptor of the From: field text 
of the message to be sent. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


The SYSPRV privilege is required to alter the From: of a message. 


MAIL$ SEND_SUBJECT 

MAIL$_SEND_SUBJECT specifies a descriptor of the Subject: field text 
of a message to be sent. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$ SEND_TO_ LINE 

MAIL$ SEND_TO_LINE specifies a descriptor of the To: field text of the 
message. The buffer address field of the item descriptor points to a 
buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$SEND_BEGIN for a description of an output item descriptor. 
Output Item Codes 


None. 





DESCRIPTION 
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If you do not specify a To: line, MAIL supplies a To: line composed of 
usernames on the To: address list. If you do not specify a CC: line, MAIL 
supplies a CC: line composed of usernames on the CC: address list. In 
either of the above cases, commas separate the usernames used. 


To modify a message’s From: field, you must have the SYSPRV privilege. 


MAIL Utility Routines 
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CONDITION 
SS$NORMAL Normal successful completion. 

VALUES wie ea 

RETURNED MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
SS$_ACCVIO Access violation. 
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MAILS$SEND_BEGIN 


Initiates processing to send a message to the users on the address list. You 
must call MAIL6SEND_BEGIN before you call any other send routine. 











FORMAT MAIL$SEND BEGIN context, in_item_list, 
out_item_list 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS _ context 
VMS usage: context 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 

Send context information to be passed to other send routines. The 
context argument is the address of a longword that contains send context 
information. 


You should specify the value of this argument as 0 in the first of a 
sequence of calls to send routines. In following calls, you should specify 
the send context value returned by this routine. 


in_item_list 

VMS usage: itmlist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


The following diagram depicts the format of a single item descriptor: 
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In_item_list Item Descriptor Fields 


buffer length 

A word specifying the length (in bytes) of the buffer that supplies the 
information needed by the routine to process the specified item code. The 
required length of the buffer depends on the item code specified in the 
item code field of the item descriptor. If the value of buffer length is too 
small, the routine truncates the data. 


item code 


A word containing a user-supplied symbolic code that specifies an option 
for the MAIL operation. These codes are defined by the $MAILDEF macro. 
See Input Item Codes for a description of these codes. 


buffer address 
A longword containing the address of the buffer that supplies information 
to the routine. 


return length address 
This field is not used. 


MAIL$SEND_BEGIN Input Item Codes 


MAIL$_SEND_PERS NAME 

MAIL$ SEND_NO PERS NAME 

MAIL$_SEND_PERS_NAME specifies the personal name text to be used 
in the message header. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


The Boolean item code MAIL$_SEND_NO_PERS_NAME specifies that no 
personal name string be used during message construction. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
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of which describes an item of information. The list of item descriptors 
is terminated by longword value of 0. The following diagram depicts the 
31 


format of a single item descriptor: 
15 0 
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Out_item_list Item Descriptor Fields 


buffer length 


A word containing a user-supplied integer specifying the length (in bytes) 
of the buffer in which the routine is to write the information. The length 
of the buffer needed depends on the item code specified in the item code 
field of the item descriptor. If the value of buffer length is too small, the 
routine truncates the data. 


item code 


A word containing a user-supplied symbolic code specifying the item of 
information that the routine is to return. These codes are defined by 
the $MAILDEF macro. See Output Item Codes for a description of these 
codes. 


buffer address 
A longword containing the user-supplied address of the buffer in which the 
routine is to write the information. 


return length address 


A longword containing the user-supplied address of a word in which the 
routine writes the actual length in bytes of the information it returned. 


Output Item Codes 


MAIL$_SEND_COPY_FORWARD 

When you specify the Boolean item code MAIL$_SEND_COPY_FORWARD, 
MAIL$SEND_BEGIN returns the value of the caller’s copy forward flag as 
a longword value. 


MAIL$_SEND_COPY_SEND 

When you specify the Boolean item code MAIL$_SEND_COPY_SEND, 
MAIL$SEND_BEGIN returns the value of the caller’s copy send flag as a 
longword value. 


MAIL$_ SEND_COPY_REPLY 

When you specify the Boolean item code MAIL$_SEND_COPY_REPLY, 
MAIL$SEND_BEGIN returns the value of the caller’s copy reply flag as a 
longword value. 
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MAIL$_SEND_USER 


When you specify MAIL$_SEND_USER, MAIL$SEND_BEGIN returns the 
process owner’s username. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 





DESCRIPTION MAIL$SEND_BEGIN creates and initializes a send context for subsequent 
calls to send routines. 





CONDITION . 

VALUES SS$NORMAL Normal successful completion. 
MAIL$_CODERR Internal system error. 

RETURNED MAIL$_CON!ITMCOD The specified item codes perform conflicting 

operations. 

MAIL$_!LLPERNAME The specified personal name string is illegal. 
MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
SS$_ACCVIO Access violation. 


Any condition values returned by $GETJPIW, LIB$FREE_VM, and LIB$GET_VM. 
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MAIL$SEND_ADD_BODYPART 


Builds the body of a message. 





FORMAT 


MAIL$SEND_ADD_BODYPART context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Send context information to be passed to send routines. The context 


argument is the address of a longword that contains send context 
information returned by MAIL$¢SEND_BEGIN. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$SEND_BEGIN for a description of an input item descriptor. 


Input Item Codes 


MAIL$ SEND_DEFAULT_NAME 

MAIL$_SEND_DEFAULT_NAME specifies the default file specification of 
a text file to be opened. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 
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MAIL$_SEND_FID 

MAIL$_SEND_FID specifies the file identifier of the text file to be opened. 
The buffer address field of the item descriptor points to a buffer that 
contains the file identifier. 


MAIL$_SEND_FILENAME 

MAIL$_SEND_FILENAME specifies the input file specification of the text 
file to be opened. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_SEND_RECORD 


MAIL$_SEND_RECORD specifies a descriptor of a text record to be 
added to the body of the message. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


When creating a message, do not specify MAIL$_ SEND_RECORD in the 
same call (or series of calls) to MAIL$SEND_ADD_BODYPART with the 
following item codes: 


¢ MAIL$_SEND_DEFAULT_NAME 
* MAIL$ SEND_FILENAME 


out_item_list 

VMS usage: itmlst_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$SEND_BEGIN for a description of an output item descriptor. 


Output Item Codes 


MAIL$ SEND_RESULTSPEC 

When you specify MAIL$_SEND_RESULTSPEC, MAIL$SEND_ADD_ 
BODYPART returns the resultant file specification identified with MAIL$_ 
SEND_FILENAME. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 
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DESCRIPTION You can use MAIL$SEND_ADD_BODYPART to specify a file that contains 
the entire message or to add a single record to a message. If the message 
is contained in a file, you call MAIL$SEND_ADD_BODYPART once, 
specifying the filename. If you want to add to the message record-by- 
record, you can call MAIL$SEND_ADD_BODYPART repeatedly, specifying 
a different record each time until you complete the message. 


You cannot specify both a filename and a record for the same message. 
You can specify MAIL$_SEND_FILENAME once or specify MAIL$_SEND_ 
RECORD one or more times. 





CONDITION | 
VALUES SS$NORMAL Normal successful completion. 
MAIL$_CONITMCOD The specified item codes define conflicting operations. 
RETURNED ~ MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
MAIL$_OPENIN The required file is missing. 
SS$_ACCVIO Access violation. 
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MAIL$SEND_END 


Terminates send processing. 











FORMAT MAIL$SEND END context, in_item_list, out_item_list 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS _ context 
VMS usage: context 
type: longword (unsigned) 
access: modify 


mechanism: by reference 

Send context information to be passed to send routines. The context 
argument is the address of a longword that contains send context 
information returned by MAIL$SEND_BEGIN. 


If send processing is successfully terminated, the value of the context 
argument is changed to 0. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by a longword of 0. 
See MAIL$SEND_BEGIN for a description of an input item descriptor. 
Input Item Codes 


None. 
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out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$SEND_BEGIN for a description of an output item descriptor. 


Output Item Codes 


None. 





DESCRIPTION The MAIL$SEND_END routine deallocates the send context as well as 
any dynamic memory allocated by previous send routine calls. 





CONDITION 
SS$_ NORMAL Normal successful completion 
VALUES noe Fo at 
RETURN ED MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
SS$_ACCVIO Access violation. 


Any condition value returned by LIBSFREE_VM 
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MAIL$SEND_MESSAGE 


Begins the actual sending of the message after the message has been 
constructed. 





FORMAT 


MAIL$SEND MESSAGE context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Send context information to be passed to send routines. The context 


argument is the address of a longword that contains send context 
information returned by MAIL$SEND_BEGIN. 


in_item_list 

VMS usage: itmlst_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$SEND_BEGIN for a description of input item descriptor. 


Input Item Codes 


MAIL$ SEND _ERROR_ENTRY 

MAIL$ SEND_ERROR_ENTRY specifies the longword address of an entry 
point to process errors during a send operation. The descriptor of the 
recipient that failed, the address of the signal array, and the user-specified 
data are passed as input to the routine. 
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MAIL$ SEND SUCCESS ENTRY 

MAIL$_SEND_SUCCESS_ENTRY specifies the longword address of an 
entry point to process successes during a send operation. The descriptor 
of the recipient that succeeded, the address of the signal array, and the 
user-specified data are passed as input to the routine. 


MAIL$ SEND_USER_DATA 
MAIL$_SEND_USER_DATA specifies a longword that MAIL$SEND_ 
MESSAGE passes to the SEND action routines. 


out_item_list 

VMS usage: itmlist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$SEND_BEGIN for a description of an output item descriptor. 
Output Item Codes 


None. 





DESCRIPTION 


The MAIL$SEND_MESSAGE routine sends a message built with the 
MAIL$SEND_ADD_BODYPART routine to every user on the address 
list. If you have not used MAIL$SEND_ADD_BODYPART to construct a 
message, MAIL$SEND_MESSAGE sends only a message header. 


If MAIL$SEND_MESSAGE encounters errors sending to an addressee, it 
calls the routine specified by MAIL$_SEND_ERROR_ENTRY. Otherwise, 
it calls the routine specified by MAIL$_SEND_SUCCESS_ENTRY. 


If either routine is not specified, MAIL$SEND_MESSAGE calls no other 
routines. 





CONDITION 
VALUES 
RETURNED 
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MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
$S$_ACCVIO Access violation. 


Any condition value returned by $CONNECT. 
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MAIL$USER_BEGIN 


Initiates access to the MAIL common user data base. You must call 
MAIL$USER_BEGIN before you call any other user routines. 











FORMAT MAIL$USER_BEGIN context, in_item_list, 
out_item_list 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS ~ context 
VMS usage: context 
type: longword (unsigned) 
access: modify 


mechanism: by reference 

User context information to be passed to other user routines. The 
context argument is the address of a longword that contains user context 
information. 


You should specify the value of this argument as 0 in the first of a 
sequence of calls to MAIL routines. In following calls, you should specify 
the user context value returned by the previous routine. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list must include at least one device item descriptor. The item 
list is terminated by longword value of 0. 
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The following diagram depicts the format of a single item descriptor: 
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In_item_list Item Descriptor Fields 


buffer length 

A word specifying the length (in bytes) of the buffer that supplies the 
information needed by the routine to process the specified item code. The 
required length of the buffer depends on the item code specified in the 
item code field of the item descriptor. If the value of buffer length is too 
small, the routine truncates the data. 


item code 

A word containing a user-supplied symbolic code that specifies an option 
for the MAIL operation. These codes are defined by the $MAILDEF macro. 
See Input Item Codes for a description of these codes. 


buffer address 
A longword containing the address of the buffer that supplies information 
to the routine. 


return length address 
This field is not used. 


MAIL$USER_BEGIN Input Item Codes 
None. 


out_item_list 

VMS usage: itmlist_3 

type: longword 

access: write only 

mechanism: by reference 
Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors 
is terminated by longword value of 0. The following diagram depicts the 
format of a single item descriptor: 


MAIL Utility Routines 
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Out_item_list Item Descriptor Fields 


buffer length 

A word containing a user-supplied integer specifying the length (in bytes) 
of the buffer in which the routine is to write the information. The length 

of the buffer needed depends on the item code specified in the item code 

field of the item descriptor. If the value of buffer length is too small, the 
routine truncates the data. 


item code 

A word containing a user-supplied symbolic code specifying the item of 
information that the routine is to return. These codes are defined by 
the $MAILDEF macro. See Output Item Codes for a description of these 
codes. 


buffer address 
A longword containing the user-supplied address of the buffer in which the 
routine is to write the information. 


return length address 
A longword containing the user-supplied address of a word in which the 
routine writes the actual length in bytes of the information it returned. 


Output Item Codes 


MAIL$ USER_AUTO_PURGE 

When you specify the Boolean item code MAIL$_USER_AUTO_PURGE, 
MAIL$USER_BEGIN returns the value of the automatic purge mail flag 
as a longword value. 


MAIL$ USER_CAPTIVE 

When you specify the Boolean item code MAIL$_USER_CAPTIVE, 
MAIL$USER_BEGIN returns the value of the UAF CAPTIVE flag as 
a longword value. 


MAIL$ USER_CC_PROMPT 

When you specify the Boolean item code MAIL$_USER_CC_PROMPT, 
MAIL$USER_BEGIN returns the value of the cc prompt flag as a longword 
value. 


MAIL$_USER_COPY_FORWARD 

When you specify the Boolean item code MAIL$_USER_COPY_FORWARD, 
MAIL$USER_BEGIN returns the value of the copy self forward flag as a 
longword value. 
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MAIL$_USER_COPY_REPLY 


When you specify the Boolean item code MAIL$_USER_COPY_REPLY, 
MAIL$USER_BEGIN returns the value of the copy self reply flag as a 
longword value. 


MAIL$ USER_COPY_SEND 

When you specify the Boolean item code MAIL$_USER_COPY_SEND, 
MAIL$USER_BEGIN returns the value of the copy self send flag as a 
longword value. 


MAIL$_USER_FORWARDING 

When you specify MAIL$_USER_FORWARDING, MAIL$USER_BEGIN 
returns the forwarding address string. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_USER_FORM 


When you specify MAIL$_USER_FORM, MAIL$USER_BEGIN returns the 
default print form string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_USER_FULL_DIRECTORY 

When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_ 
BEGIN returns complete directory path of the MAIL subdirectory. The 
buffer address field of the item descriptor points to a buffer that receives 
a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_USER_NEW_MESSAGES 

When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_ 
BEGIN returns the new message count. The buffer address field of 
the item descriptor points to a word that receives the new message count. 


MAIL$_USER_PERSONAL_NAME 

When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_ 
BEGIN returns the personal name string. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_USER_QUEUE 

When you specify MAIL$_USER_QUEUE, MAIL$USER_BEGIN returns 
the default print queue name. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 
characters long.. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 
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MAIL$_USER_RETURN_USERNAME 

When you specify MAIL$¢_USER_RETURN_USERNAME, MAIL$USER_ 
BEGIN returns the username string. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$ USER_SUB_DIRECTORY 

When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_BEGIN 
returns the subdirectory specification. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 





DESCRIPTION MAIL$USER_BEGIN creates and initializes a user data base context for 


subsequent calls to other user routines. 





CONDITION 
VALUES 
RETURNED 


SS$NORMAL Normal successful completion. 
MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
SS$_ACCVIO Access violation. 
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MAIL$USER_DELETE_INFO 


Removes a user record from the user common data base. 





FORMAT 


MAIL$USER_DELETE_INFO context, in_item_list, 
out_item_list — 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

User context information to be passed to send routines. The context 


argument is the address of a longword that contains user context 
information returned by MAIL$USER_BEGIN. 


in_item_list 

VMS usage: itmlist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list must include at least one device item descriptor. The item 
list is terminated by longword value of 0. 


See MAIL$USER_BEGIN for a description of an input item descriptor. 


Input Item Codes 


MAIL$_USER_USERNAME 


MAIL$ USER_USERNAME specifies the record to be deleted from the 
user profile data file. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 31 characters long. 


Specify a value from 0 to 31 in the buffer length field of the item 
descriptor. 


The item code MAIL$_USER_USERNAME is required. 
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out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. | 


See MAIL$USER_BEGIN for a description of an output item descriptor. 


Output Item Codes 


None. 








DESCRIPTION _ To delete a record from the MAIL common user data base, you must have 
SYSPRV privilege. 

CONDITION . 
SS$NORMAL Normal successful completion. 

VALUES Sloe eee 

RETURNED MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
MAIL$_NOSUCHUSR The specified username is not valid. 
MAIL$_NOSYSPRV The operation requires the SYSPRV privilege. 
SS$_ACCVIO Access violation. 
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MAIL$USER_END 


Terminates access to the MAIL common user data base. 











FORMAT MAIL$USER_END_ context, in_item_list, out_item_list 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS ~ context 
VMS usage: context 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 

User context information to be passed to user routines. The context 
argument is the address of a longword that contains user context 
information. 


If MAIL terminates access to the user common database successfully, the 
value of the argument context is changed to 0. 


in_item_list 

VMS usage: itmlist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list must include at least one device item descriptor. The item 
list is terminated by a longword of 0. 


See MAIL$USER_BEGIN for a description of an input item descriptor. 
Input Item Codes 


None. 
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out_item_list 

VMS usage: itmIist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$USER_BEGIN for a description of an output item descriptor. 
Output Item Codes 


None. 








DESCRIPTION The MAIL$USER_END routine deallocates the user database context 
created by MAIL$USER_BEGIN as well as all dynamic memory allocated 
by previous user routines. 

CONDITION 
SS$_NORMAL Normal successful completion. 

VALUES ee ae 

RETURNED MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 

SS$_ACCVIO Access violation. 


Any condition value returned by LIBSFREE_VM 
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MAIL$USER_GET_INFO 


Obtains information about a user from the user common data base. 





FORMAT 


MAIL$USER_GET_INFO context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

User context information to be passed to user routines. The context 


argument is the address of a longword that contains user context 
information returned by MAIL$SUSER_BEGIN. 


in_item_list 

VMS usage: itmlist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list must include at least one device item descriptor. The item 
list is terminated by longword value of 0. 


See MAIL$USER_BEGIN for a description of an input item descriptor. 


input Item Codes 


MAIL$_USER_FIRST 


The Boolean item code MAIL$_USER_FIRST specifies that MAIL$SUSER_ 
GET_INFO return information in the user profile about the first user in 
the user common database. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 
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Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_ 
USER_USERNAME in the same call to MAIL$SUSER_GET_INFO. 


MAIL$_USER_NEXT 
The Boolean item code MAIL$_USER_NEXT specifies that MAIL$USER_ 
GET_INFO return information in the user profile about the next user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_ 
USER_USERNAME in the same call to MAILSUSER_GET_INFO. 


MAIL$ USER_USERNAME 

The Boolean item code MAIL$_USER_USERNAME specifies 
MAIL$USER_GET_INFO return information in the user profile about 
a specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT and MAIL$_ 
USER_USERNAME in the same call to MAIL$USER_GET_INFO. 


out_item_list 

VMS usage: itmlst_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$USER_BEGIN for a description of an output item descriptor. 


Output Item Codes 


MAIL$_USER_AUTO_PURGE 

When you specify the Boolean item code MAIL$_USER_AUTO _ PURGE, 
MAIL$USER_GET_INFO returns the value of the automatic purge mail 
flag as a longword value. 


MAIL$ USER_CC_ PROMPT 

When you specify the Boolean item code MAIL$_USER_CC_PROMPT, 
MAIL$USER_GET_INFO returns the value of the CC prompt flag as a 
longword value. 


MAIL$_USER_COPY_FORWARD 

When you specify the Boolean item code MAIL$_ USER_COPY_FORWARD, 
MAIL$USER_GET_INFO returns the value of the copy self forward mail 
flag as a longword value. 


MAIL$ USER_COPY_REPLY 

When you specify the Boolean item code MAIL$_USER_COPY_REPLY, 
MAIL$USER_GET_INFO returns the value of the copy self reply mail flag 
as a longword value. 
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MAIL$ USER_COPY_SEND 

When you specify the Boolean item code MAIL$_USER_COPY_SEND, 
MAIL$USER_GET_INFO returns the value of the copy self send mail flag 
as a longword value. 


MAIL$ USER_EDITOR 

When you specify MAIL$_ USER_EDITOR, MAIL$USER_GET_INFO 
returns the name of the default editor. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_USER_FORWARDING 


When you specify MAIL$_USER_FORWARDING, MAIL$USER_GET_ 
INFO returns the forwarding address. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$ USER_FORM 

When you specify MAIL$_ USER_FORM, MAIL$USER_GET_INFO returns 
the default print form string. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. . 


MAIL$_USER_FULL_DIRECTORY 

When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_GET_ 
INFO returns the complete directory path of the MAIL subdirectory string. 
The buffer address field of the item descriptor points to a buffer that 
receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$ USER_NEW_MESSAGES 

When you specify MAIL$_USER_.NEW_MESSAGES, MAIL$USER_GET_ 
INFO returns the new messages count. The buffer address field of the 
item descriptor points to a word that receives the new message count as a 
longword value. 


MAIL$_USER_PERSONAL_NAME 

When you specify MAIL$ USER_PERSONAL_NAME, MAIL$USER_GET_ 
INFO returns the personal name string. The buffer address field of the 
item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 
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MAIL$ USER_QUEUE 

When you specify MAIL$_USER_QUEUE, MAIL$USER_GET_INFO 
returns the default print queue name string. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 
255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_USER_RETURN_USERNAME 

When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_ 
GET_INFO returns the username. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL$_USER_SUB_DIRECTORY 

When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_GET_ 
INFO returns the MAIL subdirectory specification string. The buffer 
address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 





_ DESCRIPTION 


The MAIL$USER_GET_INFO routine can return information about any: 
user in the user common data base. If you do not specify a username, 
MAIL$USER_GET_INFO returns information about the username 
associated with the calling process. To obtain information about a 
username other than that associated with the calling process, you must 
have SYSNAM privilege. 





CONDITION 
VALUES 
RETURNED 


SS$NORMAL Normal successful completion. 

MAIL$_CONITMCOD The specified item codes perform conflicting 
operations. 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

MAIL$_NOSUCHUSR The specified username is invalid. 

MAIL$_NOSYSPRV The specified operation requires the SYSPRV 
privilege. 

SS$_ACCVIO Access violation. 
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MAIL$USER_SET_ INFO 


Adds or modifies a specified user record in the user common data base. 





FORMAT 


MAIL$USER_SET_INFO context, in_item_list, 
out_item_list 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in 
RO. Condition values that can be returned by this routine are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

User context information to be passed to user routines. The context 


argument is the address of a longword that contains user context 
information returned by MAIL$USER_BEGIN. 


in_item_list 

VMS usage: itmist_3 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying options for the routine. The in_item_list argument is 
the address of a list of item descriptors, each of which specifies an option 
and provides the information needed to perform the operation. 


The item list must include at least one device item descriptor. The item 
list is terminated by longword value of 0. 


See MAIL$USER_BEGIN for a description of an input item descriptor. 


input Item Codes 


MAIL$_USER_CREATE_IF 


The Boolean item code MAIL$_USER_CREATE_IF specifies that 
MAIL$USER_SET_INFO should create the record for the specified user if 
it does not already exist. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 
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MAIL$ USER _SET_AUTO PURGE 
MAIL$ USER_SET NO AUTO PURGE 


The Boolean item codes MAIL$ USER_SET_ AUTO PURGE and MAIL$_ 
USER_SET_NO_AUTO_PURGE set and clear the auto purge flag for the 
specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$ USER_SET_CC_PROMPT 

MAIL$ USER_SET_NO_ CC PROMPT 

The Boolean item codes MAIL$_USER_SET_CC_PROMPT and MAIL$_ 
USER_SET_NO_CC_PROMPT set and clear the cc prompt flag for the 
specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$ USER_SET_COPY_FORWARD 

MAIL$ USER_SET_NO_COPY_FORWARD 

The Boolean item codes MAIL$ USER_SET_COPY_FORWARD and 
MAIL$ USER_SET_NO_COPY_FORWARD set and clear the copy self 
forward flag for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$ USER_SET COPY_REPLY 

MAIL$ USER_SET_NO_COPY_REPLY 

The Boolean item codes MAIL$_ USER _SET_COPY_REPLY and MAIL$_ 
USER_SET_NO_COPY_REPLY set and clear the copy self reply flag for 
the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$ USER_SET_COPY_SEND 

MAIL$ USER_SET NO COPY_SEND 

The Boolean item codes MAIL$_USER_SET_COPY_SEND and MAIL$_ 
USER_SET_NO_COPY_SEND set and clear the copy self send flag for the 
specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$_USER_SET_EDITOR 
MAIL$ USER_SET_NO EDITOR 


MAIL$_USER_SET_EDITOR specifies the name of a default editor to be 
used by the specified user. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


The Boolean item code MAIL$ USER_SET_NO_EDITOR clears the default 
editor field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 
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MAIL$_USER_SET_FORM 
MAIL$_USER_SET NO FORM 


MAIL$_USER_SET_FORM specifies the default print form string for the 
specified user. The buffer address field of the item descriptor points to a 
buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


The Boolean item code MAIL$_USER_SET_NO_FORM clears the default 
print form field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$_USER_SET_FORWARDING 
MAIL$_USER_SET_NO_FORWARDING 


MAIL$ USER_SET_FORWARDING specifies a forwarding address string 
for the specified user. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


The Boolean item code MAIL$_USER_SET_NO_FORWARDING clears the 
forwarding address field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$_USER_SET_NEW_MESSAGES 


MAIL$ USER_SET_NEW_MESSAGES specifies the new message count 
for the specified user. The buffer address field of the item descriptor 
points to a word that contains the new number of new messages. 


MAIL$_USER_SET_PERSONAL_NAME 
MAIL$_USER_SET NO PERSONAL NAME 


MAIL$_USER_SET_PERSONAL_NAME specifies a personal name string 
for the specified user. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


The Boolean item code MAIL$_USER_SET_NO_PERSONAL_NAME clears 
the personal field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$_USER_SET_QUEUE 

MAIL$ USER_SET NO QUEUE 

MAIL$_ USER_SET_QUEUE specifies a default print queue name string 
for the specified user. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


MAIL Utility Routines 
MAIL$USER_SET_INFO 


The Boolean item code MAIL$_ USER_SET_NO_QUEUE clears the default 
print queue field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$ USER_SET SUB_DIRECTORY 
MAIL$_USER_SET NO SUB DIRECTORY 


MAIL$ USER_SET_SUB_DIRECTORY specifies a MAIL subdirectory. 
The buffer address field of the item descriptor points to a buffer that 
contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item 
descriptor. 


The Boolean item code MAIL$_USER_SET_NO_SUB_DIRECTORY 
disables the use of a MAIL subdirectory for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the 
item descriptor. 


MAIL$_USER_USERNAME 

MAIL$ USER_USERNAME specifies the record to be modified in the mail 
common database and points to the username string. The buffer address 
field of the item descriptor points to a buffer that contains a character 
string 0 to 31 characters long. 


Specify a value from 0 to 31 in the buffer length field of the item 
descriptor. 


out_item_list 

VMS usage: itmist_3 

type: longword 

access: write only 

mechanism: by reference 

Item list specifying the information you want the routine to return. The 
out_item_list argument is the address of a list of item descriptors, each 
of which describes an item of information. The list of item descriptors is 
terminated by longword value of 0. 


See MAIL$USER_BEGIN for a description of an output item descriptor. 
Output Item Codes 


None. 





DESCRIPTION 


The MAIL$USER_SET_INFO routine can modify any record in the user 
common data base. If you do not specify a username, the routine modifies 
the user record associated with the calling process. 


To modify any user record other than that associated with the calling 
process, you must have SYSPRV privilege. However, if you want to add or 
modify only the forwarding address of another user, SYSNAM privilege is 
sufficient. 
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cai sa SS$NORMAL Normal successful completion. 
MAIL$_ CONITMCOD The specified item codes perform conflicting 
RETURNED operations. 
MAIL$_INVITMCOD The specified item code is invalid. 
MAIL$_INVITMLEN The specified item length is invalid. 
MAIL$_MISREQITEM The required item is missing. 
SS$_ACCVIO Access violation. 
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1 0 National Character Set (NCS) Utility Routines 


This chapter describes the National Character Set (NCS) Utility routines. 
The NCS Utility provides a common facility for defining and accessing 
collating sequences and conversion functions. Collating sequences are 
used to compare strings for sorting purposes. Conversion functions are 
used to derive an altered form of an input string based on an appropriate 
conversion algorithm. 


10.1 introduction to NCS Routines 


Using NCS, you can formulate collating sequences and conversion 
functions and register them in an NCS library. The NCS routines 
provide a programming interface to NCS that lets you access the collating 
sequences and conversion functions from an NCS library for doing string 
comparisons. 


Typically, NCS collating sequences are selective subsets of the 
multinational character set. They are used extensively in programming 
applications involving various national character sets. For example, a 
program might use the Spanish collating sequence to assign appropriate 
collating weight to characters from the Spanish national character set. 
Another program might use the French collating sequence to assign 
appropriate collating weight to characters in the French national character 
set. 


In addition to providing program access to collating sequences and 
conversion functions in an NCS library, the NCS routines provide a means 
for saving definitions in a local file for subsequent use by the comparison 
and conversion routines. 


Table 10-1 lists the NCS routines. 


Table 10-1 NCS Routines 


Routine Description 

NCS$COMPARE Compares two strings using specified collating sequence as 
comparison basis 

NCS$CONVERT Converts a string using the specified conversion function 

NCS$END_CS Terminates the use of a collating sequence by the calling 
program 

NCSS$END_CF Terminates the use of a conversion function by the calling 
program 

NCS$GET_CF Retrieves the definition of the named conversion function 


from the NCS library 


(continued on next page) 
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10.1 Introduction to NCS Routines 


Table 10-1 (Cont.) 


Routine 


NCS$GET_CS 
NCS$RESTORE_CF 
NCS$RESTORE_CS 


NCS$SAVE_CF 


NCS$SAVE_CS 


NCS Routines 


Description 


Retrieves the definition of the named collating sequence 
from the NCS library 


Permits the calling program to restore the definition of a 
“saved” conversion function from a database or an RMS file 


Permits the calling program to restore the definition of a 
“saved” collating sequence from a database or an RMS file 


Provides the calling program with information that permits 
the application to store the definition of a conversion 
function in a local database or an RMS file 


Provides the calling program with information that permits 
the application to store the definition of a collating sequence 
in a local database or an RMS file 


In a typical application, the program does the following: 


1 Prepares a string for comparison 
2 Makes a call to the NCS$GET routine, specifying the appropriate 


collating sequence 


3 Makes one or more calls to the NCS$COMPARE routine, which does 
the actual comparison 


4 Terminates the comparison with a call to the NCS$END routine 


The program can also include the use of conversion functions in 
preparation for the comparison routines. 


10.2 Examples of How to Use NCS Utility Routines 


This section includes two examples of how to use NCS utility routines in 
program applications. Example 10-1 illustrates the use of NCS utility 
routines in a FORTRAN program. 
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Example 10-1 Using NCS Routines in a FORTRAN Program 





QqaaQaa 


aAADAwW 


PAAA 


10 
20 
Lo 


PROGRAM NCS EXAMPLE 


CHARACTER*80 CSSTRING, STRING1, STRING2 
INTEGER* 4 CSLENGTH, LENGTH1, LENGTH2, CSID, STATUS, RESULT 
INTEGER* 4 NCSSGET_CS,NCSSCOMPARE, NCSSEND_CS 


CHARACTER*1 CMP (3) 


CMP (1) = ’<’ 
CMP (2) = ’=" 
CMP (3) = ’>" 


Read the name of the collating sequence.. 


WRITE (6,30) 
READ (5,15,END=999) CSLENGTH, CSSTRING 
FORMAT (’ Collating Sequence: ’) 


Get the collating sequence from the NCS library 


CSID = 0 
STATUS = NCSSGET_CS (CSID, CSSTRING(1:CSLENGTH) ) 
IF ((STATUS .AND. 1) .NE. 1) THEN 

CALL LIBSSIGNAL (%VAL (STATUS) ) 

ENDIF 


Read two strings to be compared according to the collating sequence 


WRITE (6,10) 
READ (5,15,END=999) LENGTH1,STRING1 
WRITE (6,20) 


READ (5,15,END=999) LENGTH2, STRING2 


IF (LENGTH1 .EQ. 0 .AND. LENGTH2 .EQ. 0) THEN 
GOTO 200 
ENDIF 


FORMAT (’ Stringl: ’) 
FORMAT (’ String2: ") 
FORMAT (q,a8s0) 





(continued on next page) 
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Example 10—1 (Cont.) Using NCS Routines in a FORTRAN Program 





C 
Cc Compare the strings 
Cc 

result = ncsScompare (csid, stringl(l:lengthl), string2(1:length2) ) 
C 
C Display the results of the comparison 
Cc 

WRITE (6,40) STRING1(1:LENGTH1), CMP (RESULT+2), STRING2 (1: LENGTH2) 
40 FORMAT(!’ *,A,° %,A;" 7A) 

GOTO 100 
Cc 
Cc Come here if both inputs are blank -- we are done. 
C Call NCSSEND_CS to free any storage used to hold the CS. 
Cc 
200 STATUS = NCSSEND_CS (CSID) 

IF ((STATUS .AND. 1) .NE. 1) THEN 

CALL LIBSSIGNAL (%VAL(STATUS) ) 
ENDIF 

CALL EXIT 
999 CONTINUE 

END 





Example 10-2 illustrates the use of NCS routines in a MACRO-32 
program. 


Example 10-2 Using NCS Routines in a MACRO-32 Program 





.TITLE /NCS Conversion Function Example/ 
SNAMDEF 
-PSECT DATA LONG, NOEXE, WRT 


CFID: . LONG 
LENGTH: .WORD 
CFNAME_D; 
-ASCID /EDT_VT2xx/ 
PROMPT _D: 
-ASCID / File: / 


SIZE = 1024 


-ALIGN LONG 
INFAB: S$FAB FNA=FILE, FNS=NAM$C_MAXRSS 
INRAB: $RAB FAB=INFAB, UBF=REC, USZ=SIZE 


FILE: .BLKB NAM$C_MAXRSS 
FILED: .LONG NAMSC_MAXRSS 
.ADDRESS - 
FILE 





(continued on next page) 
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Example 10-2 (Cont.) Using NCS Routines in a MACRO-32 Program 





REC: .» BLKB SIZE 
REC_D: 
- LONG SIZE 
-ADDRESS - 
REC 
DEST: 
. BLKB SIZE 
DEST_D: .LONG SIZE 
»-ADDRESS - 
DEST 


»-PSECT CODE EXE, NOWRT 
-ENTRY NCSSEXAMPLE, “M<> 


; Get the EDT VT2xx conversion function from default library. 


PUSHAL CFNAME_D 

PUSHAL CFID 

CALLS #2,G*NCSSGET_CF 
BSBW ERROR 


“oe 


; Get the file to be converted. 


“e 


PUSHAL LENGTH 

PUSHAL PROMPT _D 

PUSHAL FILE D 
CALLS #3,G*LIBSGET_INPU 
BSBW ERROR 
MOVW LENGTH, FILE D 


7 Open the file to be converted. 


SOPEN FAB=INFAB 
BSBW ERROR 
SCONNECT RAB=INRAB 
BSBW ERROR 


; Read each record from the file. 


? 
LOOP : SGET RAB=INRAB 
BLBC RO, STATUS 
; Call NCSSCONVERT to convert the input string to EDT fallback. 
7 
; (e.g., Convert form feed to <FF>, escape to <ESC>, etc...) 
7 
MOVW INRAB+RABSW_RSZ, REC_D 
PUSHAL LENGTH 
PUSHAL DEST _D 
PUSHAL REC_D 
PUSHAL CFID 
CALLS #4,G°*NCSSCONVERT 
BSBW ERROR 
MOVW LENGTH, DEST _D 
; Write result to SYSSOUTPUT. 


e 
lf 





(continued on next page) 
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Example 10-2 (Cont.) Using NCS Routines in a MACRO-32 Program 


PUSHAL DEST _D 

CALLS #1,G°LIBSPUT_ OUTPUT 
MOVW #SIZE,DEST_D 

BRB LOOP 


STATUS: CMPL RO, #RMS$_ EOF 
BEQL DONE 
BSBW ERROR 


; Call NCSSEND_CF to free any storage used to hold the conversion function. 


DONE: PUSHAL CFID 
CALLS #1,G*NCSSEND_CF 
BSBW ERROR 
RET 


; Error handling. 


ERROR: BLBC RO,10$ 
RSB 


10$: SEXIT_S RO 
. END NCSSEXAMPLE 





10.3 NCS Routines 
The following pages describe the NCS routines. 
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NCS$COMPARE Compare Strings 


The NCS$COMPARE routine compares two strings using a specified collating 
sequence as a comparison basis. 





FORMAT 


NCS$COMPARE cs _id, string_1, string_2 





RETURNS 


VMS usage: integer 

type: longword integer (signed) 
access: write only 

mechanism: by value 


Longword condition value. Most routines return a condition value in 
RO but the NCS$COMPARE routine uses RO to return the result of the 
comparison, as shown in the following table: 


Returned Value Comparison Result 


-1 string_1 is less than string_2 
0 string_1 is equal to string_2 
1 string_1 is greater than string_2 


The NCS$COMPARE routine uses the VAX Signaling Mechanism to 
indicate completion status as described under CONDITION VALUE 
SIGNALED. 





ARGUMENTS 


cs id 

VMS usage: identifier 

type: longword integer (unsigned) 

access: read only 

mechanism: by reference 

Address of a longword that NCS uses to identify a collating sequence. 
The cs_id argument is required and can be obtained by a call to the 
NCS$GET_CS routine. 


All calls to the NCS$COMPARE routine and the call to the NCS$END_CS 
routine that terminates the comparison must pass this longword identifier. 
Upon completion, the NCS$END_CS routine releases the memory used to 
store the collating sequence and sets the value of the longword identifier 
to zero. 


string_1 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Descriptor (length and address) of the first string. 
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string 2 

VMS usage: char_string 

type: character string 
access: read only 
mechanism: by descriptor 
‘Descriptor of the second string. 





DESCRIPTION The NCS$COMPARE routine compares two strings using the specified 
collating sequence as the comparison basis. The routine indicates whether 
the value of the first string is greater than, less than, or equal to the value 
of the second string. 





CONDITION . 

VALUE STR$_ILLSTRCLA Illegal string class. Severe error. The descriptor of 
string_1 or string_2, or both, contains a class code 

SIGNALED not supported by the VAX Procedure Calling and 


Condition Handling Standard. 
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NCS$CONVERT 


NCS$CONVERT Convert String 


The NCS$CONVERT routine converts a string using the specified conversion 








function. 
FORMAT NCS$CONVERT ctf_id, source, dest ,[ret_length] 
,[not_cvt] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS ~ cf_id 
VMS usage: identifier 
type: longword integer (unsigned) 
access: read only 
mechanism: by reference 
Address of a longword that NCS uses to identify a conversion function. 
The cf_id argument is required and can be obtained by a call to the 
NCS$GET_CF routine. 


All calls to the NCS$CONVERT routine and the call to the NCS$END_CF 
routine that terminates the conversion must pass this longword identifier. 
Upon completion, the NCS$END_CF routine releases the memory used to 
store the conversion function and sets the value of the longword identifier 


to zero. 

source 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 
Descriptor of source string. 


dest 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 
Descriptor of destination string. 
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ret_length 

VMS usage: word unsigned 
type: word (unsigned) 
access: write only 
mechanism: by reference 
Length of converted string. 


not_ cvt 

VMS usage: word unsigned 

type: word (unsigned) 

access: write only 

mechanism: by reference 

Number of characters in the source string that were not fully converted. 





DESCRIPTION _ Using the specified conversion function, the NCS$CONVERT routine 
converts the source string and stores the result in the specified destination. 
Optionally, the calling program can request that the routine return the 
length of the converted string as well as the number of characters which 
were not fully converted. 








CONDITION a 

VALUES NCS$_NOT_CF Name of identifier does not refer to a conversion 
function. 

RETURNED SS$_NORMAL Successful completion. 

STR$_TRU Successful completion. However, the resultant string 
was truncated because the storage allocation for the 
destination string was inadequate. 

CONDITION tea Bate . 

VALUES LBR messages (prefaced by an NCS message) might signal errors detected while the 
process is accessing the NCS library. 

SIGNALED Any value signaled by STRSCOPY_DX or STRGANALYZE_SDESC. 
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NCS$END CF End Conversion Function 


The NCS$END_CF routine terminates a conversion function. 





FORMAT 


NCS$END_CF cf_id 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


cf_id 

VMS usage: identifier 

type: longword integer (unsigned) 

access: modify 

mechanism: by reference 

Address of a longword that NCS uses to store a nonzero value identifying 
a conversion function. 


The cf_id argument is required. 





DESCRIPTION 


The NCS$END_CF routine indicates to NCS that the calling program no 
longer needs the conversion function. NCS releases the memory space 
allocated for the coversion function and sets the value of the longword 
identifier to zero. 





CONDITION 
VALUES 
RETURNED 


NCS$_NORMAL Normal successful completion. The longword identifier 
value is set to zero. 


NCS$_NOT_CF Name of identifier does not refer to a conversion 
function. 


NCS-11 


National Character Set (NCS) Utility Routines 
NCS$END_CS 


NCS$END_CS_ End Collating Sequence 


The NCS$END_CS routine terminates a collating sequence. 








FORMAT NCS$END_CS cs id 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT cs_id 
VMS usage: identifier 
type: longword integer (unsigned) 
access: modify 
mechanism: by reference 
Address of a longword that NCS uses to store a nonzero value identifying 
a collating sequence. 


The cs_id argument is required. 





DESCRIPTION The NCS$END_CS routine indicates to NCS that the calling program 
no longer needs the collating sequence. NCS releases the memory space 
allocated for the collating sequence and sets the value of the longword 
identifier to zero. 





CONDITION | 

VALU ES NCS$_NORMAL Normal successful completion. The longword identifier 
value is set to zero. 

RETURNED NCS$_NOT_CS Name of identifier does not refer to a collating 
sequence. 
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NCS$GET_CF Get Conversion Function 


The NCS$GET_CF routine retrieves the definition of the named conversion 
function from the NCS library. 








FORMAT NCS$GET_CF  cf_id/,cfname],librar] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _—_cf_id 
VMS usage: identifier 
type: longword integer (unsigned) 
access: modify 
mechanism: by reference 
Address of a longword used by NCS to identify a conversion function. 
The calling program must ensure that the longword contains zero before 
invoking the NCS$GET_CF routine because the routine stores a nonzero 
value in the longword. The nonzero value identifies the conversion 
function. All subsequent calls to the NCS$CONVERT routine and the call 
to the NCS$END_CF routine to terminate the conversion function pass the 
longword identifier. When it completes the conversion, the NCS$END_CF 
routine releases the memory used to store the conversion function and sets 
the value of the longword identifier to zero. 


The conversion function identifier enhances modular programming and 
permits concurrent use of multiple conversion functions within a program. 


The calling program should not attempt to interpret the contents of the 
longword identifier. 


The cf_id argument is required. 


cfname 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Name of the conversion function being retrieved. 
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NCS$GET_CF 


librar 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Name of the library where the conversion function is stored. 





DESCRIPTION 


The N CS$GET_CF routine extracts the named conversion function from 
the specified NCS library. 


If the calling program omits the cfname argument, an “identity” 
conversion function padded with NUL characters (hex 0) is provided. The 
identity conversion function effectively leaves each character unchanged by 
converting each character to itself. For example, A becomes A, B becomes 
B, C becomes C, and so forth. 


If the calling program omits the librar argument, NCS accesses the 
default NCS library. 





CONDITION 
VALUES 
RETURNED 


NCS$_DIAG Operation completed with signaled diagnostics. 


NCS$_NOT_CF Name of identifier does not refer to a conversion 
function. 


NCS$_NOT_FOUND Name of identifier not found in the NCS library. 





CONDITION 
VALUES 
SIGNALED 
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NCS$GET_CS Get Collating Sequence 


The NCS$GET_CS routine retrieves the definition of the named collating 
sequence from the NCS library. 





FORMAT 


NCS$GET_CS cs _id/,csname]],librar] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


cs_id 

VMS usage: identifier 

type: longword integer (unsigned) 

access: modify 

mechanism: by reference 

Address of a longword that NCS uses to store a nonzero value identifying 
a collating sequence. The calling program must ensure that the longword 
identifier contains zero before invoking the NCS$GET_CS routine. 


All subsequent calls to the NCS$COMPARE routine and the call to the 
NCS$END_CS routine that terminates the use of the collating sequence 
must pass this longword identifier. Upon completion of the comparisons, 
the NCS$END_CS routine releases the memory used to store the collating 
sequence and sets the value of the longword identifier to zero. 


The collating sequence identifier enhances modular programming and 
permits concurrent use of multiple collating sequences within a program. 


The calling program should not attempt to interpret the contents of the 
longword identifier. 


The cs_id argument is required. 


csname 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Name of the collating sequence being retrieved. 
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NCS$GET_CS 
librar 
VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 
File specification of the library where the collating sequence is stored. 





DESCRIPTION The NCS$GET_CS routine extracts the named collating sequence from the 
specified NCS library. If the calling program omits the csname argument, 
NCS creates a collating sequence that uses the “native” collating sequence 
as a basis for the comparisons. This collating sequence is padded with 
NUL characters (hex 0). 


If the calling program omits the librar argument, NCS accesses the 








default NCS library. 
CONDITION . Be . 
NCS$_DIAG Operation completed with signaled diagnostics. 
VALUES eee 
NCS$_NOT_CS Name of identifier does not refer to a collating 
NCS$_NOT_FOUND Name of identifier not found in the NCS library. 
CONDITION wae . 
VALUES LBR messages (prefaced by an NCS message) might signal errors detected while the 
process is accessing the NCS library. 
SIGNALED 
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NCS$RESTORE CF Restore Conversion Function 


The NCS$RESTORE_CF routine permits the calling program to restore the 
definition of a saved conversion function from a database or a file. 











FORMAT NCS$RESTORE_CF cf_ia/,length][, address] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 
ARGUMENTS _~ cf_id 
VMS usage: identifier 
type: longword integer (unsigned) 
access: write only 


mechanism: by reference 
Address of a longword that NCS uses to identify a conversion function. 


The cf_id argument is required. 


length 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 
Longword that the calling program uses to indicate the length of the 
conversion function being restored. 


address 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 
Longword that the calling program uses as a pointer to the conversion 
function being restored. 
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DESCRIPTION The NCS$RESTORE_CF routine, used in conjunction with the 
NCS$SAVE_CF routine, permits the application program to keep a local 
copy of the conversion function. The NCS$SAVE_CF routine obtains 
the length and location of the conversion function and returns it to the 
application program. The application program subsequently provides this 
information to the NCS$RESTORE_CF routine, which uses it to access the 
conversion function. 


This routine also does some integrity checking on the conversion function 
as it is being processed. 








CONDITION Site 
NCS$_NOT_CF Name of identifier does not refer to a conversion 

VALUE function. 

RETURNED 

CONDITION ee 

VALUES LBR messages (prefaced by an NCS message) might signal errors detected while the 
E process is accessing the NCS library. 

SIGNALED 
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NCS$RESTORE_CS Restore Collating Sequence 


The NCS$RESTORE_CS routine permits the calling program to restore the 
definition of a “saved” collating sequence from a database or a file. 











FORMAT NCS$RESTORE CS cs _idj,length][,address] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 
ARGUMENTS '~ cs _id 
VMS usage: identifier 
type: longword integer (unsigned) 
access: write only 


mechanism: by reference 
Address of a longword that NCS uses to identify a collating sequence. 


The cs_id argument is required. 


length 

VMS usage: longword_unsigned | 
type: longword (unsigned) 
access: read only 


mechanism: by reference 
Longword that the calling program uses to indicate the length of the 
collating sequence being restored. 


address 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 
Longword that the calling program uses as a pointer to the collating 
sequence being restored. 
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DESCRIPTION The NCS$RESTORE_CS routine, used in conjunction with the 
NCS$SAVE_CS routine, permits the application program to keep a 
local copy of the collating sequence. The NCS$SAVE_CS routine obtains 
the length and location of the collating sequence and returns it to the 
application program. The application program subsequently provides this 
information to the NCS$RESTORE_CS routine, which uses it to access the 
collating sequence. 


This routine also does some integrity checking on the collating sequence as 
it is being processed. 








CONDITION NCS$_NOT_CS Name of identifier does not refer to a collating 

VALUE == sequence. 

RETURNED 

CONDITION oer 

VALUES LBR messages (prefaced by an NCS message) might signal errors detected while the 
process is accessing the NCS library. 

SIGNALED 
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NCS$SAVE_CF Save Conversion Function 


The NCS$SAVE_CF routine provides the calling program with information that 
permits the application to store the definition of a conversion function in a 
local database or a file rather than in the NCS library. 











FORMAT NCS$SAVE_CF cf _idj,/ength][,address] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 
ARGUMENTS _-~ ctf_id 
VMS usage: identifier 
type: longword integer (unsigned) 
access: read only 


mechanism: by reference 
Address of a longword that NCS uses to identify a conversion function. 


The cf_id argument is required. 


length 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 
Longword used to store the length of the specified conversion function. 


address 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 
Longword used to store the address of the specified conversion function. 
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DESCRIPTION The NCS$SAVE_CF routine, used in conjunction with the NCS$_ 
| RESTORE_CF routine, permits the application program to store a 

conversion function definition in a local file or in a database. When 
the calling program specifies the conversion function identifier, NCS 
returns the location of the definition and its length in bytes, permitting 
the calling program to store the definition locally, rather than in an NCS 
library. Subsequently, the application supplies this information to the 
NCS$RESTORE_CF routine, which restores the conversion function to a 
form that can be used by the NCS$CONVERT routine. 


This routine also does some integrity checking on the conversion function 
as it is being processed. 











CONDITION NCS$ NOT_CF Name of identifier does not refer to a conversion 
am identifi ot refer to nversi 

VALUE ~ 2 function. 
RETURNED 
CONDITION oe 
VALUES LBR messages (prefaced by an NCS message) might signal errors detected while the 

process is accessing the NCS library. 
SIGNALED 
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NCS$SAVE CS Save Collating Sequence 


The NCS$SAVE_CS routine provides the calling program with information that 
permits the application program to store the definition of a collating sequence 
in a database or a file rather than in the NCS library. 











FORMAT NCS$SAVE_CS_ cs _iaj,length][,address] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 
ARGUMENTS -~— cs _id 
. VMS usage: identifier 
type: longword integer (unsigned) 
access: read only 


mechanism: by reference 
Address of a longword that NCS uses to identify a collating sequence. 


The cs_id argument is required. 


length 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 
Longword that NCS uses to indicate the length of the specified collating 
sequence to the calling program. 


address 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 
Longword that NCS uses to indicate the address of the specified collating 
sequence to the calling program. 
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DESCRIPTION = The NCS$SAVE_CS routine, used in conjunction with the NCS$_ 
RESTORE_CS routine, permits the application program to store a 
collating sequence definition in a local file or in a database. When the 
calling program specifies the collating sequence identifier, NCS returns the 
location of the definition sequence and its length in bytes, permitting 
the calling program to store the definition locally, rather than in a 
library. Subsequently, the application supplies this information to the 
NCS$RESTORE_CS routine, which restores the collating sequence to a 
form that can be used by the NCS$COMPARE routine. 


This routine also does some integrity checking on the collating sequence as 
it is being processed. 








CONDITION NCS$_NOT_CS N f identifier does not refer to a collating 
_ NOT_! ame of identi s efer to 
VALUE sequence. 
RETURNED 
CONDITION had . 
VALUES LBR messages (prefaced by an NCS message) might signal errors detected while the 
process is accessing the NCS library. 
SIGNALED 
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The print symbiont modification (PSM) routines allow you to modify the 
behavior of the print symbiont supplied with the VMS operating system. 


11.1 Introduction to PSM Routines 


The VMS print symbiont processes data for output to standard line 
printers and printing terminals by performing the following functions: 


¢ Reading the data from disk 

¢ Formatting the data 

¢ Sending the data to the printing device 

¢ Composing separation pages (flag, burst, and trailer pages) and 
inserting them into the data stream for printing 

Some of the reasons for modifying the print symbiont include the following: 


¢ To include additional information on the separation pages (flag, burst, 
and trailer) or to format them differently 


¢ ‘To filter and modify the data stream sent to the printer 


¢ To change some of the ways that the symbiont controls the printing 
device 


You might not always be able to modify the print symbiont to suit your 
needs. For example, you cannot do the following: 


¢ Modify the VMS symbiont’s control logic or the sequence in which the 
symbiont calls routines 


¢ Modify the interface between the VMS symbiont and the job controller 


If you cannot modify the VMS print symbiont to suit your needs, you might 
want to write your own symbiont. Section 11.3 describes how to write your 
own symbiont and integrate it with the VMS operating system. However, 
you should modify the VMS print symbiont, when possible, rather than 
write your own symbiont. 


The rest of this chapter contains the following information about PSM 
routines: 


¢ Section 11.2 contains an overview of the VMS print symbiont and of 
symbionts in general. It explains concepts such as “symbiont streams”; 
describes the relationship between a symbiont, a device driver, and 
the job controller; and gives an overview of the VMS print symbiont’s 
internal logic. 


This section is recommended for those who want to either modify the 
VMS print symbiont or write a new symbiont. 
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¢ Section 11.3 details the procedure for modifying the VMS print 
symbiont. It includes an overview of the entire procedure, followed 
by a detailed description of each step. 


¢ Section 11.4 contains an example of a simple modification to the VMS 
print symbiont. 


e Section 11.5 describes each PSM routine and the interface used by the 
routines you substitute for the standard PSM routines. 


11.2 VMS Print Symbiont Overview 


The VMS operating system supplies two symbionts: a print symbiont, 
which is an output symbiont, and a card reader, which is an input 
symbiont. An output symbiont receives tasks from the job controller, 
whereas an input symbiont sends jobs to the job controller. The card 
reader symbiont cannot be modified. You can modify the print symbiont, 
described in this section, using PSM routines. 


There are two types of output symbiont: device and server. A device 
symbiont processes data for output to a device, for example, a printer. A 
server symbiont also processes data but not necessarily for output to a 
device, for example, a symbiont that copies files across a network. The 
VMS operating system supplies no server symbionts. 


11.2.1 Components of the VMS Print Symbiont 


The VMS print symbiont includes the following major components: 

e PSM routines that are used to modify the print symbiont 

e Routines that implement input, format, and output services in the 
VMS print symbiont 

¢ Routines that implement the internal logic of the VMS print symbiont 


The VMS print symbiont is implemented using the Symbiont Services 
Facility. This facility provides communication and control between the 
job controller and symbionts through a set of Symbiont/Job Controller 
Interface Routines (SMB routines), which are documented in Chapter 
Chapter 12. 


All of these routines are contained in a shareable image with the file 
specification SYS$SHARE:SMBSRVSHR.EXE. 


11.2.2 Creation of the Print Symbiont Process 
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The print symbiont is a device symbiont, receiving tasks from the job 
controller and processing them for output to a printing device. In the VMS 
operating system, the existence of a print symbiont process is linked to the 
existence of at least one print execution queue that is started. 
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The job controller creates the print symbiont process by calling the Create 
Process ($CREPRC) system service; it does this whenever either of the 
following conditions occur: 


e A print execution queue is started (from the stopped state) and no 
symbiont process is running the image specified with the START 
/QUEUVE command. 


A print execution queue is started by means of the DCL command 
START/QUEUE. You can use the /PROCESSOR qualifier with the 
START/QUEUE command to specify the name of the symbiont image 
that is to service an execution queue; if you omit /PROCESSOR, then 
the default symbiont image is PRTSMB. 


¢ Currently existing symbiont processes suited to a print execution 
queue cannot accept additional devices; that is, the symbionts have 
no more available streams. In such a case, the job controller creates 
another print symbiont process. The next section discusses symbiont 
streams. 


The print symbiont process runs as a detached process. 


11.2.3 Symbiont Streams 


A stream is a logical link between a print execution queue and a printing 
device. When the queue is started (by means of START/QUEUE), the job 
controller creates a stream linking the queue with a symbiont process. 
Because each print execution queue has a single associated printing 
device (specified with the /ON=device_name qualifier in the INITIALIZE 
/QUEUE or START/QUEUE command), each stream created by the job 
controller links a print execution queue, a symbiont process, and the 
queue’s associated printer. 


A symbiont that can support multiple streams simultaneously (that 

is, multiple print execution queues and multiple devices) is termed a 
multithreaded symbiont. The job controller enforces an upper limit of 16 
on the number of streams that any symbiont can service simultaneously. 


Therefore, in the VMS operating system environment, only one print 
symbiont process is needed as long as the number of print execution 
queues (and associated printers) does not exceed 16. If there are more 
than 16 print execution queues, the job controller creates another print 
symbiont process. 


The VMS print symbiont is, therefore, a multithreaded symbiont that can 
service as many as 16 queues and devices, but you can modify it to service 
any number of queues and devices as long as the number is less than or 
equal to 16. 


A symbiont stream is said to be “active” when a queue is started on 

that stream. The print symbiont maintains a count of active streams. 

It increments this count each time a queue is started and decrements it 
when a queue is stopped with the DCL command STOP/QUEUE/NEXT or 
STOP/QUEUE/RESET. When the count falls to zero, the symbiont process 
exits. The symbiont does not decrement the count when the queue is 
paused by STOP/QUEUE. 
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Figure 11-1 shows the relationship of generic print queues, execution print 
queues, the job controller, the print symbiont, printer device drivers, and 
printers. The lines connecting the boxes denote streams. 


Figure 11-1 Multithreaded Symbiont 
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11.2.4 Symbiont and Job Controller Functions 


This section compares the roles of the symbiont and job controller in the 
execution of print requests. You issue print requests using the PRINT 
command. 
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The job controller uses the information specified on the PRINT command 
line to determine the following: 


Which queue to place the job in ((QUEUE, /REMOTE, /LOWERCASE, 
and /DEVICE) 


How many copies to print ((COPIES and /JOB_COUNT) 


Scheduling constraints for the job (/PRIORITY, /AFTER, /BLOCK_ 
LIMIT, /HOLD, /FORM, /CHARACTERISTICS, and /RESTART) 


How and whether to display the status of jobs and queues (/NOTIFY, 
/OPERATOR, and [DENTIFY) 


The print symbiont, on the other hand, interprets the information supplied 
with the qualifiers that specify this information: 


Whether to print file separation pages (/BURST, /FLAG, and 
/TRAILER) 


Information to include when printing the separation pages (/NAME 
and /NOTE) 


Which pages to print (PAGES) 


How to format the print job (FEED, /SPACE, and /PASSALL) 
How to set up the job (SETUP) 
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The print symbiont, not the job controller, performs all necessary device- 
related functions. It communicates with the printing device driver. For 
example, when a print execution queue is started (by means of START 
/QUEUE/ON=device_name) and the stream is established between the 
queue and the symbiont, the symbiont parses the device name specified by 
the /ON qualifier in the START/QUEUE command, allocates the device, 
assigns a channel to it, obtains the device characteristics, and determines 
the device class. In versions of the VMS operating system prior to Version 
4.0, the job controller performed these functions. 


The print symbiont’s output routine returns an error to the job controller 
if the device class is neither printer nor terminal. 


11.2.5 Print Symbiont Internal Logic 


The job controller deals with units of work called jobs, while the print 
symbiont deals with units of work called tasks. A print job can consist 

of several print tasks. Thus, in the processing of a print job, the job 
controller’s role is to divide a print job into one or more print tasks, which 
the symbiont can process. The symbiont reports the completion of each 
task to the job controller, but the symbiont contains no logic to determine 
that the print job as a whole is complete. 


In the processing of a print task, the symbiont performs three basic 
functions: input, format, and output. The symbiont performs these 
functions by calling routines to perform each function. 


The following steps describe the action taken by the symbiont in processing 
a task: 


1 The symbiont receives the print request from the job controller and 
stores it in a message buffer. 


2 The symbiont searches its list of input routines and selects the first 
input routine that is applicable to the print task. 


3 The input routine returns a data record to the symbiont’s input buffer 
or in a buffer supplied by the input routine. 


4 Data in the input buffer is moved to the symbiont’s output buffer by 
the formatting routines, which format it in the process. 


5 Data in the output buffer is sent to the printing device by the output 
routine. 


6 When an input routine completes execution, that is, when it has no 
more input data to process, the symbiont selects another applicable 
input routine. Steps 3, 4, and 5 are repeated until all applicable input 
routines have executed. 


7 The symbiont informs the job controller that the task is complete. 
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Figure 11-2 illustrates the steps taken by the symbiont in the processing 
of a print task. 


Figure 11-2 Symbiont Execution Sequence or Flow of Control 
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As Figure 11-2 shows, most of the input routines execute in a specified 
sequence. This sequence is defined by the symbiont’s main control routine. 
You cannot modify this main control routine; thus, you cannot modify the 
sequence in which symbiont routines are called. 


The input routines that do not execute in sequence are called “demand 
input routines.” These routines are called whenever the service they 
provide is required and include the page header, page setup, and library 
module input routines. 


The symbiont can perform input, formatting, and output functions 
asynchronously; that is, the order in which the symbiont calls the input, 
formatting, and output routines can vary. For example, the symbiont can 
call an input routine, which returns a record to the input buffer; it can 
then call the format routine, which moves that record to the output buffer; 
and then it can call the output routine to move that data to the printing 
device. This sequence results in the movement of a single data record from 
disk to printing device. 


On the other hand, the symbiont can call the input and formatting 
routines several times before calling the output routine for a single buffer. 
The buffer can contain one or more formatted input records. In some cases 
an output buffer might contain only a portion of an input record. 


In this way the symbiont can buffer input records; then call the format 
routine, which moves one of those records to the output buffer; and finally 
call the output routine, which moves that data to the printing device. 
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Note, however, that the formatting routine must be called once for each 
input record. 


Similarly, the symbiont can buffer several formatted records before calling 
the output routine to move them to the printing device. 


The symbiont requires this flexibility in altering the sequence in which 
input, format, and output routines are called for reasons of efficiency (high 
rate of throughput) and adaptability to various system parameters and 
system events. 


The value specified with the call to PSM$PRINT determines the maximum 
size of the symbiont’s output buffer, which cannot be larger than the 
value of the SYSGEN parameter MAXBUF. If the buffer is very small, the 
symbiont might need to call its output routine one or more times for each 
record formatted. If the buffer is large, the symbiont will buffer several 
formatted records before calling the output routine to move them to the 
printing device. 


11.3 Symbiont Modification Procedure 


To modify the VMS print symbiont, perform the following steps. These 
steps are described in more detail in the sections that follow. 


1 Determine the modification needed. The modification might involve 
changing the way the symbiont performs a certain function, or it might 
involve adding a new function. 


2 Determine where to make the modification. This involves selecting a 
function and determining where that function is performed within the 
symbiont’s execution sequence. You specify a function by calling the 
PSM$REPLACE routine and specifying the code that identifies the 
function. 


Some codes correspond to symbiont-supplied routines. When you 
specify one of these codes, you replace that routine with your routine. 
Other codes do not correspond to symbiont-supplied routines. When 
you specify one of these codes, you add your routine to the set of 
routines the symbiont executes. Table 11-1 lists these codes. 


3 Write the routine. Because the symbiont calls your routine, your 
routine must have one of three call interfaces, depending on whether 
it is an input, format, or output routine. See the descriptions of the 
USER-INPUT-ROUTINE, USER-FORMAT-ROUTINE, and USER- 
OUTPUT-ROUTINE routines, which follow the descriptions of the 
PSM routines. 


4 Write the symbiont-initialization routine. This routine executes when 
the symbiont is first activated by the job controller. It initializes the 
symbiont’s internal database; specifies, by calling PSM$REPLACE, 
the routines you have supplied; activates the symbiont by calling 
PSM$PRINT; and performs any necessary cleanup operations when 
PSM$PRINT completes. 


5 Construct the modified symbiont. This involves compiling your 
routines, then linking them. 
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6 Integrate the modified symbiont with the system. This involves placing 
the executable image in SYS$SYSTEM, identifying the symbiont image 
to the job controller, and debugging the symbiont. 


As mentioned previously, you identify each routine you write for the 
symbiont by calling the PSM$REPLACE routine. The code argument for 
this routine specifies the point within the symbiont’s execution sequence 
at which you want your routine to execute. You should know which code 
you will use to identify your routine before you begin to write the routine. 
Section 11.3.6 provides more information about these codes. 


11.3.1 Guidelines and Restrictions 
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The following guidelines and restrictions apply to the writing of any 
symbiont routine: 


¢ Do not use the process-permanent files identified by the logical names 
SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND. 


¢ The symbiont code should be linked against SMBSRVSHR.EXE in 
order to define the following status codes: 


— PSM$_FLUSH 
— PSM$_FUNNOTSUP 
— PSM$_PENDING © 
— PSM$_SUSPEND 
— PSM$_EOF 
— PSM$_BUFFEROVF 
— PSM$ NEWPAGE 
— PSM$_ESCAPE 
— PSM$_INVVMSOSC 
— PSM$_MODNOTFND 
— PSM$_NOFILEID 
— PSM$_OSCTOOLON 
— PSM$_TOOMANYLEV 
— PSM$_INVITMCOD 

¢ Do not use the system services SYS$HIBER and SYS$WAKE. 


¢ Use the following two Run-Time-Library routines for allocation and 
deallocation of memory: LIB$GET_VM and LIB$FREE_VM. 


¢ Minimize the amount of time that your routine spends executing 
at AST level. The job controller sends messages to the symbiont by 
means of user-mode ASTs; the symbiont cannot receive these ASTs 
while your user routine is executing at AST level. 


¢ The symbiont can call your routines at either AST level or non-AST 
level. 
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If your routine returns any error-condition value (low bit clear), the 
symbiont aborts the current task and notifies the job controller. 

Note that, by default, an error-condition value returned during the 
processing of a task causes the job controller to abort the entire job. 
However, this default behavior can be overridden. See the description 
of the /RETAIN qualifier of the DCL commands START/QUEUE, 
INITIALIZE/QUEUE, and SET QUEUE in the VMS DCL Dictionary. 


The symbiont stores the first error-condition value (low bit clear) 
returned during the processing of a task. The symbiont’s file-errors 
routine, an input routine (code PSM$K_FILE_ERRORS), places the 
message text associated with this condition value in the symbiont’s 
input stream. The symbiont prints this text at the end of the listing, 
immediately before the trailer pages. 


The symbiont sends this error-condition value to the job controller; the 
job controller then stores this condition value with the job record in the 
job controller’s queue file. The job controller also writes this condition 

value in the accounting record for the job. 


If you choose to return a condition value when an error occurs, you 
should choose one from the system message file. This lets system 
programs access the message text associated with the condition 
value. Specifically, the Accounting and SHOW/QUEUE utilities 

and the job controller will be able to translate the condition value 

to its corresponding message text and to display this message text as 
appropriate. 


This guideline applies to input, input-filter, and output-filter routines, 


‘and to the symbiont’s use of dynamic string descriptors in these 


routines. 


The simplest way for an input routine to pass the data record to the 
symbiont is for it to use an RTL string-handling routine (for example, 
STR$COPY_R). These routines use dynamic string descriptors to 
point to the record they have handled to copy the record from your 
input buffer to the symbiont-supplied buffer specified in the funedesc 
argument to the input routine. 


By default, the symbiont initializes a dynamic string descriptor that 
your input routine can use to describe the data record it returns. 
Specifically, the symbiont initializes the DSC$B_DTYPE field of the 
string descriptor with the value DSC$K_DTYPE_T (which indicates 
that the data to which the descriptor points is a string of characters) 
and initializes the DSC$B_CLASS field with the value DSC$K_ 
CLASS_D (which indicates that the descriptor is dynamic). 


Alternatively, the input routine can pass a data record to the symbiont 
by providing its own buffer and passing a static string descriptor that 
describes the buffer. To do this, you must redefine, using the following 
steps, the fields of the descriptor to which the funcdese argument 
points: 


1 Initialize the field DSC$B_CLASS with the value DSC$K_CLASS_ 
S (which indicates that the descriptor points to a scalar value or a 
fixed-length string). 
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2 Initialize the field DSC$A_POINTER with the address of the buffer 
that contains the data record. 


3 Initialize the field DSC$W_LENGTH with the length, in bytes, of 
the data record. 


Each time the symbiont calls the routine to read some data, the 
symbiont reinitializes the descriptor to make it a dynamic. descriptor. 
Consequently, if you want to use the descriptor as a static descriptor, 
your input routine must initialize the descriptor as described 
previously every time it is called to perform a reading operation. 


Input-filter routines and output-filter routines return a data record to 
the symbiont by means of the func_desc_2 argument. The symbiont 
initializes a descriptor for this argument the same way it does for 
descriptors used by input routine described previously. Thus, the 
guidelines described for the input routine apply to the input-filter 
routine and output-filter routine. 


11.3.2 Writing an Input Routine 
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This section provides an overview of the logic used in the VMS print 
symbiont’s main input routine, and it discusses the way in which the VMS 
print symbiont handles carriage-control effectors. 


The print symbiont calls your input routine, supplying it with arguments. 
Your routine must return arguments and condition values to the print 
symbiont. For this reason, your input routine must use the interface 
described in the description of the USER-INPUT-ROUTINE. 


When the print symbiont calls your routine, it specifies a particular 
request in the fune argument. Each function has a corresponding code. 


Your routine must provide the functions identified by the codes PSM$K_ 
OPEN, PSM$K_READ, and PSM$K_CLOSE. Your routine need not 
respond to the other function codes, but it can if you want it to. If your 
routine does not provide a function that the symbiont requests, it must 
return the condition value PSM$_FUNNOTSUP to the symbiont. 


The description of the fune argument of the USER-INPUT-ROUTINE 
describes the codes that the symbiont can send to an input routine. 


See Section 11.3.5 for additional information about other function codes 
used in the user-written input routine. 


For each task that the symbiont processes, it calls some input routines 
only once, and some more than once; it always calls some routines and 
calls others only when needed. 


Table 11—1 lists the codes that you can specify when you call the 
PSM$REPLACE routine to identify your input routine to the symbiont. 
The description of the PSM$REPLACE routine describes these routines. 
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11.3.2.1 Internal Logic of the Symbiont’s Main Input Routine 
The internal logic of the symbiont’s main input routine, as described in 
this section, is subject to change without notice. This logic is summarized 
here. This summary is not intended as a tutorial on the writing of a 
symbiont’s main input routine, although it does provide insight into such a 
task. 


A main input routine is one that the symbiont calls to read data from the 
file that is to be printed. A main input routine must perform three sets of 
tasks: one set when the symbiont calls the routine with an OPEN request, 
one set when the symbiont calls with a READ request, and one set when 
the symbiont calls with a CLOSE request. 


The following table names the codes that identify each of these three 
requests and describes the tasks that the VMS symbiont’s main input 
routine performs for each of these requests: 


Code Action Taken by the Input Routine 


PSM$K_OPEN An OPEN request. When the main input routine receives this 
request code, it does the following: 


1 Opens the input file. 
2 Stores information about the input file. 


3 Returns the type of carriage control used in the input file. If 
this routine cannot open the file, it returns an error. 


Note that the VMS print symbiont’s main input routine performs 
these tasks when it receives the PSM$K_START_TASK function 
code, rather than the PSM$K_OPEN function code. 


This atypical behavior occurs because some of the information 
stored by the main input routine must be available for other 
input routines that execute before the main input routine. For 
example, information about file attributes and record formats is 
needed by the symbiont’s separation-page routines, which print 
flag and burst pages. 


Consequently, if you supply your own main input routine, some 
of the information about the file being printed that appears on 
the standard separation pages is not available, and the symbiont 
prints a message on the separation page stating so. 
The symbiont receives the file-identification number from the job 
controller in the SMBMSG$K_FILE_IDENTIFICATION item of 
the requesting message and uses this value rather than the file 
specification to open the main input file. 

PSM$K_READ A READ request. When the main input routine receives this 
request, it returns the next record from the file. In addition, when 
the carriage control used by the data file is PSM$K_CC_PRINT, 
the main input routine returns the associated record header. 


PSM$K_CLOSE A CLOSE request. When the main input routine receives this 
request, it closes the input file. 
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11.3.2.2 Symbiont Processing of Carriage Control 


Each input record can be thought of as consisting of three parts: leading 
carriage control, data, and trailing carriage control. Taken together, these 
three parts are called the composite data record. 


Leading and trailing carriage control are determined by the type of 
carriage control used in the file and explicit carriage-control information 
returned with each record. For embedded carriage control, however, 
leading and trailing carriage control is always null. 


The type of carriage control returned by the main input routine on the 
PSM$K_OPEN request code determines, for that invocation of the input 
routine, how the symbiont applies carriage control to each record that the 
main input routine returns on the PSM$K_READ request code. 


Note that, for all four carriage control types, the first character returned 
on the firsts PSM$K_READ call to an input routine receives special 
processing. If that character is a linefeed or a formfeed and if the symbiont 
is currently at line 1, column 1 of the current page, then the symbiont 
discards that linefeed or formfeed. 


The Four Types of Carriage Conirol 


The following table briefly describes each type of carriage control and how 
the symbiont’s main input routine processes it. For a detailed explanation 
of each of these types of carriage control, refer to the description of the 
FAB$B_RAT field of the FAB block in the VMS Record Management 
Services Manual. 


Type of Carriage Control Symbiont Processing 


Embedded Leading and trailing carriage control are embedded 
in the data portion of the input record. Therefore, 
the symbiont supplies no special carriage control 
processing; it assumes that leading and trailing 
carriage control are null. 


FORTRAN The first byte of each data record contains a 
FORTRAN carriage-control character. This character 
specifies both the leading and trailing carriage control 
for the data record. The symbiont extracts the first 
byte of each data record and interprets that byte as 
a FORTRAN carriage-control character. If the data 
record is empty, the symbiont generates a leading 
carriage control of linefeed and a trailing carriage 
control of carriage return. 
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Type of Carriage Control Symbiont Processing 


PRN Each data record contains a two-byte header that 
contains the carriage-control specifier. The first byte 
specifies the carriage control to apply before printing 
the data portion of the record. The second byte 
specifies the carriage control to apply after printing 
the data portion. The abbreviation PRN stands for 
print-file format. 

Unlike other types of carriage control, PRN carriage 

control information is returned through the funcarg 

argument of the main input routine; this occurs with 

the PSM$K_READ request. The funcarg argument 

specifies a longword; your routine writes the 2-byte 

PRN carriage contro! specifier into the first two bytes 
of this longword. 

Implied The symbiont provides a leading linefeed and a 
trailing carriage return. But if the data record consists 
of a single formfeed, the symbiont sets to null the 
leading and trailing carriage control for that record, 
and the leading carriage control for the record that 
follows it. 


11.3.3 Writing a Format Routine 


To write a format routine, follow the modification procedure described in 
Section 11.3. Do not replace the VMS symbiont’s main format routine. 
Instead, modify its action by writing input and output filter routines. 
These execute immediately before and after the main format routine, 
respectively. The main formatting routine uses an undocumented and 
nonpublic interface; you cannot replace the main formatting routine. The 
DCL command PRINT/PASSALL bypasses the main format routine of the 
print symbiont. 

See Section 11.3.5 for additional information about other function codes 
used in the user-written formatting routine. 


11.3.3.1 Internal Logic of the Symbiont’s Main Format Routine 
The main format routine contains all the logic necessary to convert 
composite data records to a data stream for output. Actions taken by 
the format routine include the following: 


e Tracking the current column and line | 


¢ Implementing the special processing of the first character of the first 
record 


¢ Implementing the alignment data mask specified by the DCL command 
START/QUEUE/ALIGN=MASK 


e¢ Handling margins as specified by the forms definition 


e Initiating processing of page headers when specified by the DCL 
command PRINT/HEADER 


e Expanding leading and trailing carriage control 
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e Handling line overflow 

e Handling page overflow 

¢ Expanding tab characters to spaces for some devices 
¢ Handling escape sequences 

e Accumulating accounting information 


¢ Implementing double-spacing when specified by the DCL command 
PRINT/SPACE 


¢ Implementing automatic page ejection when specified by the DCL 
command PRINT/FEED 


The symbiont’s main format routine uses a special rule when processing 
the first character of the first composite data record returned by an input 
routine. (A composite data record is the input data record and a longword 
that contains carriage-control information for the input data record.) This 
rule is that if the first character is a vertical format effector (formfeed or 
linefeed) and if the symbiont has processed no printable characters on the 
current page (that is, the current position is column 1, line 1), then that 
vertical format effector is discarded. 


11.3.4 Writing an Output Routine 
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To write an output routine, follow the modification procedure described in 
Section 11.3. 


The print symbiont calls your output routine. Input arguments are 
supplied by the print symbiont; output arguments and status values 
are returned by your routine to the print symbiont. For this reason, 
your output routine must have the call interface that is described in the 
USER-OUTPUT-ROUTINE routine. 


When the print symbiont calls your routine, it specifies in one of the input 
arguments—the func argument—the reason for the call. Each reason has 
a corresponding function code. 


There are several function codes that the print symbiont can supply when 
it calls your output routine. Your routine must contain the logic to respond 
to the following function codes: PSM$K_OPEN, PSM$K_WRITE, PSM$K_ 
WRITE_NOFORMAT, and PSM$K_CLOSE. 


It is not required that your output routine contain the logic to respond to 
the other function codes, but you can provide this logic if you want to. 


A complete list and description of all relevant function codes for output 
routines is provided in the description of the func argument of the USER- 
OUTPUT-ROUTINE routine. 


See Section 11.3.5 for additional information about other function codes. 
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11.3.4.1 Internal Logic of the Symbiont’s Main Output Routine 
When the symbiont calls the main output routine with the PSM$K_OPEN 
function code, the main output routine takes the following steps: 


1. Allocates the print device 

2 Assigns a channel to the device 

3 Obtains the device characteristics 
4 


Returns the device-status longword in the funcarg argument (for 
more information, see the description of the SMBMSG$K_DEVICE_ 
STATUS message item in Chapter 12 


5 Returns an error if the device is not a terminal or a printer 


When this routine receives a PSM$K_WRITE service request code, it sends 
the contents of the symbiont output buffer to the device for printing. 


When this routine receives a PSM$K_WRITE_NOFORMAT service request 
code, it sends the contents of the symbiont output buffer to the device for 
printing and suppresses device drive formatting as appropriate for the 
device in use. 


When this routine receives a PSM$K_CANCEL service request code, it 
requests the device driver to cancel any outstanding output operations. 


When this routine receives a PSM$K_CLOSE service request code, it 
deassigns the channel to the device and deallocates the device. 


11.3.5 Other Function Codes 


A status PSM$_PENDING might not be returned whenever the symbiont 
notifies user-written input, output, and format routines using the following 
message function codes: . 


Function Code Description 

PSM$K_START_STREAM Job controller sends a message to the symbiont to 
start a queue 

PSM$K_START_TASK Symbiont parses a message from job controller 
directing it to start a queue 

PSM$K_PAUSE_TASK Job controller sends a message to the symbiont to 
suspend processing of the current task 

PSM$K_STOP_STREAM Job controller sends a message to the symbiont to 
stop the queue 

PSM$K_STOP_TASK Job controller sends a message to the symbiont to 
stop the task 

PSM$K_RESUME_TASK Job controller sends a message to the symbiont to 


resume processing of the current task 
PSM$K_RESET_STREAM Same as PSM$K_STOP_STREAM 


PSM-15 


Print Symbiont Modification (PSM) Routines 
11.3 Symbiont Modification Procedure 


11.3.6 Writing a Symbiont Initialization Routine 
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Writing a symbiont initialization routine involves writing a program that 
calls the following: 


1 PSM$REPLACE once for each routine (input, output, or format) that 
you have written. PSM$REPLACE identifies your routines to the 
symbiont. 


2 PSM$PRINT exactly once after you have identified all your service 
routines using PSM$REPLACE. 


Table 11-1 lists all routine codes that you can specify in the 
PSM$REPLACE routine. Choosing the correct routine code for your 
routine is important because the routine code specifies when the symbiont 
will call your routine. The functions of these routines are described further 
in the description of the PSM$REPLACE routine. 


Column one in Table 11-1 lists each routine code. 


For those input routines that execute in a predefined sequence, the second 
column contains a number showing the order in which that input routine 
is called relative to the other input routines for a single file job. If the 
routine does not execute in a predefined sequence, the second column 
contains the character x. 


Column three specifies whether the routine is an input, format, or output 
routine; this information directs you to the section describing how to write 
a routine of that type. 


Column four specifies whether there is a symbiont-supplied routine 
corresponding to that routine code. The codes for the input-filter and 
output-filter routines, which have no corresponding routines in the VMS 
symbiont, allow you to specify new routines for inclusion in the symbiont. 


Table 11-1 Routine Codes for Specification to PSM$REPLACE 


Routine Code Sequence Function Supplied 


PSM$K_JOB_SETUP 1 Input Yes 
PSM$K_FORM_SETUP 2 Input Yes 
PSM$K_JOB_FLAG 3 Input Yes 
PSM$K_JOB_BURST 4 Input Yes 
PSM$K_FILE_SETUP 5 Input. Yes 
PSM$K_FILE_FLAG 6 Input Yes 
PSM$K_FILE_BURST 7 Input Yes 
PSM$K_FILE_SETUP_2 8 Input Yes 
PSM$K_MAIN_INPUT 9 Input Yes 
PSM$K_FILE_INFORMATION 10 Input Yes 
PSM$K_FILE_ERRORS 11 Input Yes 


(continued on next page) 
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Table 11-1 (Cont.) Routine Codes for Specification to PSM$REPLACE 


Routine Code Sequence Function Supplied 
PSM$K_FILE_TRAILER 12 Input Yes 
PSM$K_JOB_RESET 13 Input Yes 
PSM$K_JOB_TRAILER 14 Input Yes 
PSM$K_JOB_COMPLETION 15 Input Yes 


PSM$K_PAGE_SETUP Xx 
PSM$K_PAGE_HEADER x 

PSM$K_LIBRARY_INPUT x 

PSM$K_INPUT_FILTER x Formatting No 
PSM$K_MAIN_FORMAT x 

PSM$K_OUTPUT_FILTER X 

PSM$K_OUTPUT x 


input Yes 
Input Yes 
Input Yes 


Formatting Yes 
Formatting No 
Output Yes 





11.3.7 Integrating a Modified Symbiont 


To integrate your user routine and the symbiont initialization routine, 
perform the following steps; note that the sequence of steps described here 
assumes that you will be debugging the modified symbiont: 


1 


Compile or assemble the user routine and the symbiont initialization 
routine into an object module. | 


Enter the following DCL command: 
$ LINK/DEBUG your-symbiont 


The file name your-symbiont is the object module built in step 

1. Symbols necessary for this link operation are located in 

the shareable images SYS$SHARE:SMBSRVSHR.EXE and 
SYS$LIBRARY:IMAGELIB.EXE. The linker automatically searches 
these shareable images and extracts the necessary information. 


Place the resulting executable symbiont image in SYS$SYSTEM. 


Locate two unallocated terminals: one at which to issue DCL 
commands and one at which to debug the symbiont image. 


Log in on one of the terminals under UIC [1,4], which is the system 
manager’s account. This terminal is the one at which you enter DCL 
commands. Do not log in at the other terminal. 


Enter the following DCL command: 


$ SET TERMINAL/NODISCONNECT/PERMANENT _iTeu: 


The variable _TTcu: is the physical terminal name of the terminal at 
which you want to debug (the terminal you are not logged in at). The 
underscore (_) and colon (:) characters must be specified. 
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7 


10 


11 


Enter the following DCL commands: 


$ DEFINE/GROUP DBGSINPUT TTcu: 
$ DEFINE/GROUP DBGSOUTPUT TTcu: 


The variable _TTcu: specifies the physical terminal name of the 
terminal at which you will be debugging. Note that other users having 
a UIC with group number 1 should not use the debugger at the same 
time. 


Initialize the queue by entering the following DCL command: 
$ INITIALIZE/QUEUE/PROCESSOR= your-symbiont /ON= printer_name 


The symbiont image specified by the file name your-symbiont must 
reside in SYS$SYSTEM. Note too that the /PROCESSOR qualifier 
accepts only a file name; the device, directory, and file type default to 
SYS$SYSTEM:.EXE. 


The /ON qualifier specifies the device that will be served by the 
symbiont while you debug the symbiont. 


Enter the following DCL command to execute the modified symbiont 
routine: 


$ PRINT/HEADER/QUEUE=queue-id 


Enter the following DCL command to start the queue and invoke the 
debugger: 


$ START/QUEUE queue-name 


After you debug your symbiont, relink the symbiont by entering the 
following DCL command: 


$ LINK/NOTRACEBACK/NODEBUG your-symbiont 


Deassign the logical names DBG$INPUT and DBG$OUTPUT so that 
they will not interfere with other users in UIC group 1. 


11.4 Example of Using the PSM Routines 


Example 11—1 shows how to use PSM routines to supply a page header 
routine in a MACRO program. 
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Example 11-1 Using PSM Routines to Supply a Page Header Routine in a MACRO Program 





Ne Ne Ne Ne Ne 


=e Ne Ne 


e 
f 


. 
tA 


° 
’ 


“Ne 


“ee Ne 


-TITLE EXAMPLE - 
-IDENT ’V03-000’ 


++ 
THIS PROGRAM SUPP 
ROUTINE TO THE ST 
INCLUDES THE SUBM 
THE FULL FILE SPE 
THE HEADER LINE I 
PRINTED ON A SECO 


.-LIBRARY /SYSSLI 
System definitions 


SPSMDEF 
SSMBDEF 
SDSCDEF 


Define argument offsets 


CONTEXT 
WORK_AREA 
FUNC 
FUNC_DESC 
FUNC_ARG 


Macro to create dynamic 


.-MACRO D_DESC 


Example user modified symbiont 


LIES A USER WRITTEN PAGE HEADER 
ANDARD SYMBIONT. THE PAGE HEADER 
ITTER’S ACCOUNT NAME AND USER NAME, 
CIFICATION, AND THE PAGE NUMBER. 

S UNDERLINED BY A ROW OF DASHES 

ND HEADER LINE. 


BRARY : LIB.MLB/ 


; Symbiont definitions 
; Message item definitions 
; Descriptor definitions 


for user supplied services called by symbiont 


04 ; symbiont context 

08 7; user context 

12 ; function code 

16 ; function dependent descriptor 
20 ; function dependent argument 
descriptors 


-WORD 0 ; DSCSW_LENGTH = 0 
- BYTE DSCSK_DTYPE T ; DSCSB_DTYPE = STRING 
-BYTE DSC$K_CLASS_D ; DSC$B_CLASS = DYNAMIC 
-LONG 0 ; DSCSA_POINTER = 0 
. ENDM 
Storage for page header information 
FILE: D_DESC ; file name descriptor 
USER: D_DESC 7 user name descriptor 
ACCOUNT: D_DESC ; account name descriptor 
PAGE: . LONG 0 7 page number 
LINE: . LONG 0 ; line number 


FAO control string and 
“[Taccount, name] f 


FAO_CTRL: 
FAO CTRL 2: 
FAO DESC: 


work buffer. Header format: 


ilename ....... . Page 9999" 

-ASCID /!71<[!AS, !AS] !AS!>Page 9999/ 

-ASCID /!4UL/ 

. LONG 80 ; work buffer descriptor 


-ADDRESS FAO BUFF 


FAO_BUFF: 


- BLKB 


’ 


80 work buffer 





(continued on next page) 
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Example 11-1 (Cont.) Using PSM Routines to Supply a Page Header Routine in a MACRO 


Program 





° 
, 


; Own storage for values passed by reference 


° 
4 


CODE: . LONG 0 ; service or item code 
STREAMS: . LONG 1 7; number of simultaneous streams 
BUFSIZ: . LONG 2048 ; output buffer size 
LINSIZ: . WORD 81 ; line size for underlines 
; Main routine -- invoked at image startup 
, 
START: .WORD 0 ; save nothing because this routine uses only RO and Rl 


e 
tA 


; Supply private page header routine 


MOVZBL #PSMS$K_PAGE HEADER, CODE 


PUSHAL HEADER 

PUSHAL CODE 

CALLS #2,G°PSMSREPLACE 
BLBC RO,10$ 


; Transfer control to the standard symbiont 


PUSHAL BUFSIZ 

PUSHAL STREAMS 

CALLS #2,G*°PSMSPRINT 
108: RET 


. 
, 


; Page header routine 


HEADER: .WORD 0 


; Check function code 


ry 
, 


CMPL #PSMSK_START_ TASK, @FUNC (AP) 


BEQL 20$ 
CMPL #PSMSK_READ, @FUNC (AP) 
BNEQ 15$ 
BRW 50$ 

15S: CMPL #PSMSK_OPEN, @FUNC (AP) 
BNEQ 16$ 
BRW 66$ 

168: MOVL #PSM$_FUNNOTSUP, RO 


RET 


; Starting a new file 


208: 
CLRL PAGE 
MOVZBL #2,LINE 


“eo Ne Ne Nae Ne 


‘oe Ne Ne 


set the service code 
address of modified routine 
address of service code 
replace the routine 

exit if any errors 


address of output buffer size 
address of number of streams 
invoke standard symbiont 


save nothing 


new task? 
branch if so 
READ function? 


branch if so 
OPEN function? 


branch if so 
unsupported function 
return to symbiont 


reset the page number 
and the line number 
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Example 11-1 (Cont.) Using PSM Routines to Supply a Page Header Routine in a MACRO 


Program 





; Get the account name 


MOVZBL 
PUSHAL 
PUSHAL 
PUSHAL 
CALLS 
BLBC 


; Get the file 


MOVZBL 
PUSHAL 
PUSHAL 
PUSHAL 
CALLS 
BLBC 


Get the user 


“Ne Ne Me 


MOVZBL 
PUSHAL 
PUSHAL 
PUSHAL 
CALLS 
BLBC 


™e 


#SMBMSGS$K_ACCOUNT_NAME, CODE 
ACCOUNT 

CODE 

@CONTEXT (AP) 
#3,G*PSMSREAD_ ITEM DX 

RO, 40$ 


‘Ne 


“Me Ne Ne Ne 


name 


#SMBMSGS$K_FILE_ SPECIFICATION, CODE 
FILE ; 
CODE 

@CONTEXT (AP) 
#3,G*PSMSREAD_ ITEM _DX 
RO, 40$ 


we Se Ne Ne ON 


name 


#SMBMSGSK_USER_NAME, CODE 
USER 

CODE 

@CONTEXT (AP) 
#3,G°*PSMSREAD_ ITEM DX 
RO, 40$ 


“eo “Se Se Me Ne 


se 


set item code 

address of descriptor 

address of item code 

address of symbiont ctx value 
read it 

branch if any errors 


set item code 
of descriptor 
of item code 
of symbiont ctx value 


address 
address 
address 
read it 
branch if any errors 


set item code 

address of descriptor 

address of item code 

address of symbiont ctx value 
read it ; 

branch if any errors 


; Set up the static header information that is constant for the task 


SFAO_S 


BLBC 
MOVL 


408; RET 


. 
’ 


FAO CTRL, - 


#PSMS$_FUNNOTSUP, RO 


CTRSTR = ; 
OUTBUF = FAO DESC, - ; 
P1 = #ACCOUNT, - ; 
P2 = #USER, - : 
P3 = #FILE ; 
RO, 408 ; 


; Read a page header 


508: 
DECL 
BEOL 
BLSS 


LINE 
60$ 
70$ 


me Ne 


se 


FAO control string desc 

output buffer descriptor 

account name descriptor 

user name descriptor 

file name descriptor 

branch if any errors 

unsupported function 

return usupported status or error 


decrement the line number 
branch if second read 
branch if third read 
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Example 11-1 (Cont.) Using PSM Routines to Supply a Page Header Routine in a MACRO 


° 
7 


Program 


; Insert the page number into the header 


INCL 
MOVAB 
SFAO_S 


MOVAB 
BLBC 


; Copy the line 


PUSHAB 

PUSHL 

CALLS 
55$: RET 


° 
f 


; Second line -- 


60S: 
PUSHL 
PUSHAL 
CALLS 
BLBC 
MOVL 
MOVL 
MOVAB 
65S: MOVB 
CMPL 
BGTRU 
MOVB 
668: MOVZBL 
67$: RET 


o 
v 


; Done with this 


PAGE 

FAO BUFF+76,FAO DESC+4 
CTRSTR = FAO CTRL 2, - 
OUTBUF = FAO DESC, - 
Pl = PAGE 


FAO BUFF, FAO DESC+4 
RO,55$ 


to the symbiont’s buffer 


FAO DESC 
FUNC_DESC (AP) 
#2,G*STRSCOPY_DX 


underline header 


FUNC_DESC (AP) 
LINSI2 
#2,G°STRSGET1_ Dx 
RO, 67S 
FUNC_DESC (AP) , R1 
4(R1),R1 

80 (R1),RO 
#°A/-/, (R1) + 
RO,R1 

65$ 

#10, (R1) + 

#SS$ NORMAL, RO 


page header 


Ne Ne Ne Ne Ne Ne Ne 


se Se Ne Ne 


™e “oe “Se Ne Ne Ye Se Ne Ne Se Ne Ne Ne 





increment the page number 
point to page number buffer 
FAO control string desc 
output buffer descriptor 
page number 

point to work buffer 

return if error 


work buffer descriptor 
symbiont descriptor 

copy to symbiont buffer 
return success or any error 


symbiont descriptor 
number of bytes to reserve 
reserve the space 

exit if error 

get address of descriptor 
get address of buffer 

set up transfer limit 
fill with dashes 

reached limit? 

branch if not 

extra line feed 

set success 

return 








708: 
MOVL #PSM$_EOF, RO 7; return end of input 
MOVZBL #2,LINE ; reset line counter 
RET ; return 
- END START 

PSM Routines 
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PSM$PRINT Invoke VMS-Supplied Print Symbiont 


The PSM$PRINT routine invokes the VMS-supplied print symbiont. 


PSM$PRINT must be called exactly once after all user service routines have 
been specified using PSM$REPLACE. 








FORMAT PSM$PRINT [streams] [,bufsiz] [,worksiz] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ streams 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Maximum number of streams that the print symbiont is to support. The 
streams argument is the address of a longword containing this number, 
which must be in the range 1 to 16. If you do not specify streams, a 
default value of 1 is used. Thus, by default, a user-modified print symbiont 
supports one stream, which is to say that it is a single-threaded symbiont. 


A stream (or thread) is a logical link between a print execution queue 
and a printing device. When a symbiont process can accept simultaneous 
links to more than one queue, that is, when it can service multiple queues 
simultaneously, the symbiont is said to be multithreaded. 


bufsiz 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Maximum buffer size in bytes that the print symbiont is to use for output 
operations. The bufsiz argument is the address of a longword containing 
the specified number of bytes. 


The print symbiont actually uses a buffer size that is the smaller of (1) 
the value specified by bufsiz or (2) the SYSGEN parameter MAXBUF. 

If you do not specify bufsiz, then the print symbiont uses the value of 

MAXBUF. 


The print symbiont uses this size limit only for output operations. Output 
operations involve the placing of processed or formatted pages into a buffer 
that will be passed to the output routine. 
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PSM$PRINT 


The print symbiont uses the value specified by bufsiz only as an upper 
limit; most buffers that it writes will be smaller than this value. 


worksiz 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Size in bytes of a work area to be allocated for the use of user routines. 
The worksiz argument is the address of a longword containing this size 
in bytes. If you do not specify worksiz, no work area is allocated. 


A separate area of the specified size is allocated for each active symbiont 
stream. 





DESCRIPTION 


The PSM$PRINT routine must be called exactly once after all user 
routines have been specified to the print symbiont. Each user routine 
is specified to the symbiont in a call to the PSPM$REPLACE routine. 


The PSM$PRINT routine allows you to specify whether the print symbiont 
is to be single-threaded or multithreaded, and if multithreaded, how many 
streams or threads it can have. In addition, this routine allows you to 
control the maximum size of the output buffer. 





CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL Normal successful completion. 


This routine also returns any condition values returned by the $SETPRV, 
$GETSYI, $PURGWS, and $DCLAST system services, as well as any 
condition values returned by the SMB$INITIALIZE routine documented in 
Chapter 12. 
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PSM$READ_ITEM_DX Obtain Value of Message 


items 


The PSM$READ_ITEM_DxX routine obtains the value of message items that 
are sent by the job controller and stored by the VMS symbiont. 





FORMAT 


PSM$READ_ITEM_ DX request_ id ,item , buffer 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


request_id 

VMS usage: address 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Request identifier supplied by the symbiont to the user routine currently 
calling PSM$READ_ITEM_DX. The symbiont always supplies a request 
identifier when it calls a user routine with a service request. The 
request_id argument is the address of a longword containing this request 
identifier value. 


Your user routine must copy the request identifier value that the symbiont 
supplies (in the request_id argument) when it calls your user routine. 
Then, when your user routine calls PSM$READ_ITEM_DX, it must supply 
(in the request_id argument) the address of the request identifier value 
that it copied. 


item 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Item code that identifies the message item that PSM$READ_ITEM_DX is 
to return. The item argument is the address of a longword that specifies 
the item’s code. 


For a complete list and description of each item code, refer to the 
documentation of the item argument in ane SMB$READ_MESSAGE_ 
ITEM routine in Chapter 12. 
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buffer 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 

Buffer into which PSM$READ_ITEM_DX returns the specified 
informational item. The buffer argument is the address of a descriptor 
pointing to this buffer. 


The PSM$READ_ITEM_DX routine returns the specified informational 
item by copying that item to the buffer using one of the STR$6COPY_xx 
routines documented in the VMS Run-Time Library Routines Volume. 





DESCRIPTION 


The PSM$READ_ITEM_DX routine obtains the value of message items 
that are sent by the job controller and stored by the VMS symbiont. 

You use PSM$READ_ITEM_DxX to obtain information about the task 
currently being processed, for example, the name of the file being printed 
(SMBMSG$K_FILE_SPECIFICATION) or the name of the user who 
submitted the job (SMBMSG$K_USER_NAME). 





CONDITION 
VALUES 
RETURNED 
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SS$_ NORMAL Normal successful completion. . 
PSM$_INVITMCOD Invalid item code specified in the item argument. 
This routine also returns any condition values returned by any of the 


STR$COPY_xx routines documented in the VMS Run-Time Library 
Routines Volume. 
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PSMSREPLACE Declare User Service Routine 


The PSM$REPLACE routine substitutes a user service routine for a symbiont 
routine or adds a user service routine to the set of symbiont routines. 


You must call PSM$REPLACE once for each routine that you replace or add. 





FORMAT 


PSM$REPLACE code,routine 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 





ARGUMENTS 


code 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Routine code that identifies the symbiont routine to be replaced by a 
user service routine. The code argument is the address of a longword 
containing the routine code. 


Some routine codes identify routines that are supplied with the VMS 
symbiont; when you specify such a routine code, you replace the symbiont- 
supplied routine with your service routine. 


Two routine codes identify routines that are not supplied with the VMS 
symbiont; when you specify such a routine code, your service routine is 
added to the set of symbiont routines. 


Table 11-1 lists each routine code in the order in which it is called within 
the symbiont execution stream; this table also specifies whether a routine 
code identifies an input, formatting, or output routine and whether the 
routine is supplied with the VMS symbiont. 


The routine codes are defined by the $PSMDEF macro. The following 
pages list each routine code in alphabetical order; the description of each 
code includes the following information about its corresponding routine: 


¢ Whether the routine is supplied by the VMS symbiont 
¢ Whether the routine is an input, formatting, or output routine 
¢ Under what conditions the routine is called 


¢ What task the routine performs 
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Routine Codes 


PSM$K_FILE_BURST 

This code identifies a symbiont-supplied input routine; it is called 
whenever a file burst page is requested. This routine obtains information 
about the job, formats the file burst page, and returns the contents of 
the page to the input buffer. A file burst page follows a file flag page and 
precedes the contents of the file. 


PSM$K_FILE_ERRORS 

This code identifies a symbiont-supplied input routine; it is called when 
errors have occurred during the job. This routine places the error message 
text in the input buffer. 


PSM$K_FILE_FLAG 

This code identifies a symbiont-supplied input routine; it is called 
whenever a file flag page is requested. This routine obtains information 
about the job, formats the file flag page, and returns the contents of the 
page to the input buffer. A flag page follows the job burst page (if any) 
and precedes the file burst page (if any). It contains such information as 
the file specification of the file and the name of the user issuing the print 
request. 


PSM$K_FILE_INFORMATION 

This code identifies a symbiont-supplied input routine; it is called when 
the file information item has been specified by the job controller. This 
routine expands the file information item to text and returns it to the 
input buffer. 


PSM$K_FILE_SETUP 

This code identifies a symbiont-supplied input routine; it is always called. 
This routine queues any specified file-setup modules for insertion in the 
input stream when the PSM$K_FILE_SETUP routine closes. 


PSM$K_FILE_SETUP_2 

This code identifies a symbiont-supplied input routine; it is always called. 
This routine returns a formfeed to ensure that printing of the file begins 
at the top of the page. This routine is called just before the main input 
routine. 


PSM$K_FILE_TRAILER 

This code identifies a symbiont-supplied input routine; it is called 
whenever a file trailer page is requested. This routine obtains information 
about the job, formats the file trailer page, and returns the contents of the 
page to the input buffer. A trailer page follows the last page of the file 
contents. 


PSM$K_MAIN_FORMAT 

This code identifies the symbiont-supplied formatting routine; it is always 
called. This routine performs numerous formatting functions. You cannot 
replace this routine. 


PSM$K_FORM_SETUP 
This code identifies a symbiont-supplied input routine; it is always called. 


This routine queues any specified form-setup modules for insertion in the 
input stream when the PSM$K_FORM_SETUP routine closes. 
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PSM$K_INPUT_FILTER 

This code identifies a format routine that is not supplied by the VMS 
symbiont. If the routine is supplied by the user, it is always called 
immediately prior to the symbiont-supplied formatting routine (routine 
code PSM$K_MAIN_FORMAT). An input-filter service routine is useful 
for modifying input data records and their carriage control before they are 
formatted by the symbiont. 


PSM$K_JOB_BURST 

This code identifies a symbiont-supplied input routine; it is called 
whenever a job burst page is requested. This routine obtains information 
about the job, formats the job burst page, and returns the contents of the 
page to the input buffer. A job burst page follows the job flag page and 
precedes the file flag page (if any) of the first file in the job. It is similar to 
a file burst page except that it appears only once per job and only at the 
beginning of the job. 


PSM$K_JOB_COMPLETION 

This code identifies a symbiont-supplied input routine; it is always called. 
This routine returns a formfeed, which causes any output buffered by the 
device to be printed. 


PSM$K_JOB_FLAG 

This code identifies a symbiont-supplied input routine; it is called 
whenever a job flag page is requested. This routine obtains information 
about the job, formats the job flag page, and returns the contents of the 
page to the input buffer. A job flag page is similar to a file flag page except 
that it appears only once per job, preceding the job burst page (if any). 


PSM$K_JOB_RESET 

This code identifies a symbiont-supplied input routine; it is always called. 
This routine queues any specified job-reset modules for insertion in the 
input stream when the PSM$K_JOB_RESET routine closes. 


PSM$K_JOB_SETUP 

This code identifies a symbiont-supplied input routine; it is always called. 
This routine checks to see if this is the first job to be printed on the device, 
and if so, it issues a formfeed and then performs a job reset. See the 
description of the PSM$K_JOB_RESET routine for information about job 
reset. 


PSM$K_JOB_TRAILER 

This code identifies a symbiont-supplied input routine; it is called 
whenever a job trailer page is requested. This routine obtains information 
about the job, formats the job trailer page, and returns the contents of the 
page to the input buffer. A job trailer page is similar to a file trailer page 
except that it appears only once per job, as the last page in the job. 


PSM$K_MAIN_INPUT 


This code identifies a symbiont-supplied input routine; it is always called. 
This routine opens the file to be printed, returns input records to the input 
buffer, and closes the file. 
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PSM$K_LIBRARY_INPUT 


This code identifies a symbiont-supplied input routine; it is called when an 
input routine closes and when modules have been requested for insertion 
in the input stream. This routine returns the contents of the specified 
modules, one record per call. You cannot replace this routine. 


PSM$K_OUTPUT_FILTER 

This code identifies a formatting routine that is not supplied by the 

VMS symbiont. If the routine is supplied by the user, it is always called. 
This routine executes prior to the symbiont output routine (routine code 
PSM$K_OUTPUT). An output-filter service routine is useful for modifying 
output data buffers before they are passed to the output routine. 


At the point where the output-filter routine executes within the symbiont 
execution stream, the input data is no longer in record format; instead, the 
data exists as a stream of characters. The carriage control, for example, is 
embedded in the data stream. Thus, the output buffer might contain what 
was once a complete record, part of a record, or several records. _ 


PSM$K_PAGE_HEADER 

This code identifies a symbiont-supplied input routine; it is called once at 
the beginning of each page if page headers are requested. This routine 
returns to the input buffer one or more lines containing information about 
the file being printed and the current page number. This routine is called 
only while the main input routine is open. 


PSM$K_PAGE_SETUP 

This code identifies a symbiont-supplied routine; it is called at the 
beginning of each page if page-setup modules were specified. This routine 
queues any specified page-setup modules for insertion in the input stream 
when the PSM$K_ PAGE SETUP routine closes. This routine is called 
only while the main input routine is open. 


PSM$K_OUTPUT 

This code identifies the symbiont-supplied output routine; it is always 
called. This routine writes the contents of the output buffer to the printing 
device, but it also performs many other functions. 


routine 

VMS usage: procedure 

type: procedure entry mask 
access: read only 


mechanism: by reference 
User service routine that is to replace a symbiont routine or to be included. 
The routine argument is the address of the user routine entry point. 





DESCRIPTION 
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The PSM$REPLACE routine must be called each time a user service 
routine replaces a symbiont routine or is added to a set of symbiont 
routines. 


The code argument specifies the symbiont routine to be replaced. The 

routine codes that can be specified in the code argument are of two types: 
those that identify existing print symbiont routines and those that do not. 
All the routine codes are similar, however, in the sense that each supplies 
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a location within the print symbiont execution stream where your routine | 
can execute. 


By selecting a routine code that identifies an existing symbiont routine, 
you effectively disable that symbiont routine. The service routine that 
you specify might or might not perform the function that the disabled 
symbiont routine performs. If it does not, the net effect of the replacement 
is to eliminate that function from the list of functions performed by the 
print symbiont. Exactly what your service routine does is up to you. 


By selecting a routine code that does not identify an existing symbiont 
routine (those that identify the input-filter and output-filter routines), your 
service routine has a chance to execute at the location signified by the 
routine code. Because the service routine you specify to execute at this 
location does not replace another symbiont routine, your service routine is 
an addition to the set of symbiont routines. 


As mentioned, each routine code identifies a location in the symbiont 
execution stream, whether or not it identifies a symbiont routine. 
Table 11-1 lists each routine code in the order in which the location it 
identifies is reached within the symbiont execution stream. 





CONDITION 
VALUE 
RETURNED 


SS$_NORMAL Normal successful completion. 
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PSM$REPORT Report Completion Status 


The PSM$REPORT routine reports to the print symbiont the completion status 
of an asynchronous operation initiated by a user routine. 


Such a user routine must return the completion status PSM$_PENDING. 
PSM$REPORT must be called exactly once for each time a user routine 
returns the status PSM$_PENDING. 





FORMAT 


PSMS$REPORT _request_id [, status] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under _ 
CONDITION VALUE RETURNED. 





ARGUMENTS 
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request_id 

VMS usage: address 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Request identifier supplied by the symbiont to the user routine at the time 
the symbiont called the user routine with the service request. The user 
routine must return the completion status PSM$_PENDING on the call 
for this service request. The request_id argument is the address of a 
longword containing the request identifier value. 


The symbiont calls the user routine with a request code that specifies the 
function that the symbiont expects the user routine to perform. In the call, 
the symbiont also supplies a request identifier, which serves to identify 
the request. If the user routine initiates an asynchronous operation, a 
mechanism is required for notifying the symbiont that the asynchronous 
operation has completed and for providing the completion status of the 
operation. 


The PSM$REPORT routine conveys the above two pieces of information. 
In addition, PSM$REPORT returns to the symbiont (in the request_ 

id argument) the same request identifier value as that supplied by the 
symbiont to the user routine that initiated the operation. In this way, the 
symbiont synchronizes the completion status of an asynchronous operation 
with that invocation of the user routine that initiated the operation. 


Any user routine that initiates an asynchronous operation must, therefore, 
copy the request identifier value that the symbiont supplies (in the 
request_id argument) when it calls the user routine. The user routine 
will later need to supply this value to PSM$REPORT. 
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In addition, when the user routine returns, which it does before the 
asynchronous operation has completed, the user routine must return the 
status PSM$_PENDING. 


status 

VMS usage: cond_value 

type: longword (unsigned) 
access: read only 


mechanism: by reference 

Completion status of the asynchronous operation that has completed. The 
status argument is the address of a longword containing this completion 
status. The status argument is optional; if it is not specified, the symbiont 
assumes the completion status SS$_NO 


The user routine that initiates the asynchronous operation must test 
for the completion of the operation and must supply the operation’s 
completion status as the status argument to the PSM$REPORT routine. 
The DESCRIPTION section describes this procedure in greater detail. 


If the completion status specified by status has the low bit clear, the 
symbiont aborts the task. 





DESCRIPTION 


An asynchronous operation is an operation that, once initiated, executes 
“off to the side” and need not be completed before other operations can 
begin to execute. Asynchronous operations are common in symbiont 
applications because a symbiont, if it is multithreaded, must handle 
concurrent I/O operations. 


One example of a user routine that performs an asynchronous operation 
is an output routine that calls the $QIO system service to write a record 
to the printing device. When the user output routine completes execution, 
the I/O request queued by $QIO might not have completed. In order to 
synchronize this I/O request, that is, to associate the I/O request with the 
service request that initiated it, you should use the following mechanism: 


1 In making the call to $QIO, specify the astadr and iosb arguments. 
The astadr argument specifies an AST routine to execute when 
the queued output request has completed, and the iosb argument 
specifies an I/O status block to receive the completion status of the I/O 
operation. Item 3 describes some functions that your AST routine will 
need to do. 


2 Have the user output routine return the status PSM$_PENDING. 
3 Write the AST routine to perform the following functions: 


a. Copy the completion status word from the I/O status block to a 
longword location that you will specify as the status argument in 
the call to PSPM$REPORT. 


b. Call PSM$REPORT. Specify as the request_id argument the 
request identifier that was supplied by the print symbiont in the 
original call to the user output routine. 
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ie SS$_NORMAL Normal successful completion. 


RETURNED 
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USER-FORMAT-ROUTINE Invoke User-Written 


Format Routine 


The user-written USER-FORMAT-ROUTINE performs format operations. 
The symbiont’s control logic routine calls your format routine at one of two 
possible points within the symbiont’s execution stream. You select this point 
by specifying one of two routine codes when you call the PSM$REPLACE 
routine. 


A user format routine can be an input filter routine (routine code PSM$K_ 
INPUT_FILTER) or an output filter routine (routine code PSM$K_OUTPUT_ 
FILTER). The main format routine (routine code PSM$K_MAIN_FORMAT) 
cannot be replaced. 


A user format routine must use the call interface described here. 











FORMAT USER-FORMAT-ROUTINE  request_id,work_area 
,func ,func_desc_1 
,func_arg_1 ,func_desc_2 
,func_arg_2 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS __ request_id 


VMS usage: address 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Request identifier supplied by the symbiont when it calls your format 
routine. The request_id argument is the address of a longword containing 
this request identifier value. 


work_area 

VMS usage: address 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Work area supplied by the symbiont for the use of your format routine. 
The symbiont supplies the address of this area when it calls your routine. 
The work_area argument is a longword containing the address of the 
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work area. The work area is a section of memory that your format routine 
can use for buffering and other internal operations. 


The size of the work area allocated is specified by the work_size argument 
in the PSM$PRINT routine. If you do not specify work_size in the call to 
PSM$PRINT, no work area is allocated. — 


In a multithreaded symbiont, a separate work area is allocated for each 
thread. This work area is shared by all user routines. The work area is 
initialized to zero when the symbiont is first started. 


func 

VMS usage: function_code 

type: longword (unsigned) 
access: read only 


mechanism: by reference 

Function code specifying the service that the symbiont expects your format 
routine to perform. The func argument is the address of a longword into 
which the symbiont writes this function code. 


The function code specifies the reason the symbiont is calling your format 
routine or, in other words, the service that the symbiont expects your 
routine to perform at this time. 


The PSM$K_FORMAT function code is the only one to which your format 
routine must respond. When the symbiont calls your format routine with 
this function code, your routine must move a record from the input buffer 
to the output buffer. 


The symbiont can call your format routine with other function codes. 
Your routine should return the status PSM$ FUNNOTSUP (function not 
supported) when it is called with any of the following function codes 

or with any undocumented function code. When the status PSM$_ 
FUNNOTSUP is returned, the symbiont performs its normal action as 
if no format routine were supplied. To suppress the symbiont’s normal 
action, you should return SS$_NORMAL. 


PSM$K_START_STREAM PSM$K_STOP_STREAM 
PSM$K_START_TASK PSM$K_PAUSE_TASK 
PSM$K_RESUME_TASK PSM$K_STOP_TASK 


PSM$K_RESET_STREAM 


These function codes correspond to message items, which are discussed in 
more detail in Section 11.3.5, sent by the job controller to the symbiont. 


Other function codes correspond to internal symbiont mechanisms that are 
not part of the public interface to the print symbiont. 


Your format routine should return the status PSM$_FUNNOTSUP or 
SS$_NORMAL when it is called with a message function code or with a 
private function code. 


func_desc_1 

VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
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Descriptor supplying an input record to be processed by the format routine. 
The func_desc_1 argument is the address of a string descriptor. By using 
this argument, the symbiont supplies the input record that your format 
routine is to process. Because this descriptor can be of any valid string 
type, your format routine should use the Run-Time Library string routines 
to analyze this descriptor and to manipulate the input record. 


func_arg_1 

VMS usage: vector_byte_unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference 

Carriage control for the input record supplied by func_desc_1. The func_ 
arg_1 argument is the address of a 4-byte vector that specifies the carriage 
control for the input record. The following diagram depicts the format of 
this 4-byte vector. 


31 23 15 7 0 
Trailing Carriage—Control Leading Carriage—Control 
Information Information 
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Bytes 0 and 1 describe the leading carriage control to apply to the input 
data record; bytes 2 and 3 describe the trailing carriage control. 


Byte 0 is a number specifying the number of times the carriage control 
specifier in byte 1 is to be repeated preceding the input data record. Byte 
2 is a number specifying the number of times the carriage control specifier 
in byte 3 is to be repeated following the input data record. 


For values of the carriage control specifier from 1 to 255, the specifier is 
the ASCII character to be used as carriage control. Value 0 represents the 
ASCII “newline” sequence. Newline consists of a carriage return followed 
by a linefeed. 


The func_arg_1 argument is not used if your format routine is an 
output filter routine (routine code PSM$K_OUTPUT_FILTER). See the 
DESCRIPTION section for more information. 


func_desc_2 


VMS usage: char_string 

type: character string 

access: write only 

mechanism: by reference 

Descriptor of a buffer to which your format routine writes the formatted 
output record. The func_desc_2 argument is the address of a string 
descriptor. 


Your format routine must return the formatted data record by using the 
func_desc_2 argument. 


Your format routine should use the Run-Time Library string routines to 
write into the buffer specified by this descriptor. 
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func_arg 2 


VMS usage: vector_byte_unsigned 

type: byte (unsigned) 

access: write only 

mechanism: by reference 

Carriage control for the output record returned in func_desc_2. The 
func_arg_2 argument is the address of a 4-byte vector that specifies the 
carriage control for the output record. See the description of func_arg_1 
for the contents and format of this 4-byte vector. 


If you do not process the carriage-control information supplied in func_ 
arg_1 , then you should copy that value into func_arg_2. Otherwise, the 
carriage-control information will be lost. 


The func_arg_2 argument is not used if your format routine is an 
output filter routine (routine code PSM$K_OUTPUT_FILTER). See the 
DESCRIPTION section for more information. 





DESCRIPTION 
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When used, the func_arg_1 argument describes carriage-control 
information for the input data record, and the func_arg_2 argument 
describes carriage-control information for the output data record. 


The input data record is passed to the format routine (input filter or 
output filter) for processing, and the output data record is returned by the 
format routine (input filter or output filter). 


One of the tasks performed by the main format routine (routine code 
PSM$K_MAIN_FORMAT) is that of embedding the carriage-control 
information (specified by func_arg_1) into the data record (specified by 
func_desc_1). Thus, the output data (specified by func_desc_2) contains 
embedded carriage control and is thus no longer in record format; it is, 
therefore, properly referred to as an output data stream rather than an 
output data record. 


Similarly, the output filter routine (routine code PSM$K_OUTPUT_ 
FILTER), which executes after the main format routine, uses neither 

the func_arg_1 nor func_arg_2 argument; the data it receives (via func_ 
desc_1) and the data it returns (via func_desc_2) are data streams, not 
data records. 


However, the input filter routine (routine code PSM$K_INPUT_FILTER), 
which executes before the main format routine, uses both func_arg_1 
and func_arg_2. This is so because the main format routine has not 
yet executed, and so the carriage control information has not yet been 
embedded in the data record. 
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USER-FORMAT-ROUTINE 
CONDITION . . 
VALUES SS$_ NORMAL Successful completion. The user format routine has 
completed the function that the symbiont requested. 
RETURNED PSM$_FUNNOTSUP Function not supported. The user format routine 


does not support or does not recognize the function 
code supplied by the symbiont. To ensure future 
compatibility, your format routine should return this 
status for any unrecognized status codes. 


This routine also returns any error condition values that you have coded 
your format routine to return. Refer to Section 11.3.1 for more information 
about error condition values. 
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USER-INPUT-ROUTINE Invoke User-Written Input 
Routine 
The user-written USER-INPUT-ROUTINE performs input operations. The 


symbiont calls your routine at a specified point in its execution stream; you 
specify this point using the PSM$REPLACE routine. 








FORMAT USER-INPUT-ROUTINE request_id,work_area ,func 
,funcdesc ,funcarg 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ request_id 
VMS usage: address 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Request identifier value supplied by the symbiont when it calls your input 
routine. The request_id argument is the address of a longword containing 
this request identifier value. 


If your input routine initiates an asynchronous operation (for example, 
a call to the $QIO system service), your input routine must copy the 
request identifier value specified by request_id because this value must 
later be passed to the PSM$REPORT routine. See the description of the 
PSM$REPORT routine for more information. 


work_area 


VMS usage: address 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Work area supplied by the symbiont for the use of your input routine. The 
symbiont supplies the address of this area when it calls your routine. The 
work_area argument is a longword into which the symbiont writes the 
address of the work area. The work area is a section of memory that your 
input routine can use for buffering and for other internal operations. 


The size of the work area allocated is specified by the work_size argument 
in the PSM$PRINT routine. If you do not specify work_size in the call to 
PSM$PRINT, no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each 
thread. This work area is shared by all user routines. The work area is 
initialized to zero when the symbiont is first started. 


func 

VMS usage: function_code 

type: longword (unsigned) 
access: read only 


mechanism: by reference 
Function code supplied by the symbiont when it calls your input routine. 
The func argument is the address of a longword containing this code. 


The function code specifies the reason the symbiont is calling your input 
routine or, in other words, the function that the symbiont expects your 
routine to perform at this time. 


Most function codes require or allow additional information to be passed 
in the call by means of the funcdese and funcarg arguments. The 
description of each input function code, therefore, includes a description of 
how these two arguments are used with that function code. 


Following is a list of all the function codes that the symbiont can specify 
when it calls your input routine (function codes applicable only to format 
and output routines are explained in the descriptions of the USER- 
FORMAT-ROUTINE and USER-OUTPUT-ROUTINE, respectively); all 
function codes are defined by the $PSMDEF macro. 


Function Codes for Input Routines 


PSM$K_CLOSE 

When the symbiont calls your routine with this function code, your routine 
must terminate processing by releasing any resources it might have 
allocated. 


The symbiont calls your routine with PSM$K_CLOSE when (1) your 
routine returns from a PSM$K_READ function call with the status PSM$_ 
EOF (end of input) or with any error condition, or (2) the symbiont 
receives a task-abortion request from the job controller. 


In any event, the symbiont always calls your input routine with 
PSM$K_CLOSE if your routine returns successfully from a PSM$K_OPEN 
function call. This guaranteed behavior ensures that any resources your 
routine might have allocated on the OPEN will be released on the CLOSE. 


PSM$K_GET_KEY 

Typically, the use of both the PSM$K_GET_KEY and PSMK$K_ 
POSITION_TO_KEY function codes is appropriate only for a main input 
routine (routine code PSM$K_MAIN_INPUT). 


When the symbiont calls your routine with this function code, your routine 
can do one of two things: (1) return PSM$_FUNNOTSUP (function not 
supported) or (2) return an input marker string to the symbiont. 


If your routine returns PSM$_FUNNOTSUP to this function code, then 
your routine must also return PSM$_ FUNNOTSUP if the symbiont 
subsequently calls your routine with the PSM$K_POSITION_TO_KEY 
function code. By returning PSM$_FUNNOTSUP, your routine is choosing 
not to respond to the symbiont request. 
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If your routine chooses to respond to the PSM$K_GET_KEY function code, 
your routine must return an input marker string to the symbiont; this 
input marker string identifies the input record that your input routine 
most recently returned to the symbiont. Subsequently, when the symbiont 
calls your input routine with the PSM$K_POSITION_TO_KREY function 
code, the symbiont passes your input routine one of the input marker 
strings that your input routine has returned on a previous PSM$K_GET_ 
KEY function call. Using this marker string, your input routine must 
position itself so that, on the next PSM$K_READ call from the symbiont, 
your input routine will return (or reread) the input record identified by the 
marker string. 


Coding your input routine to respond to PSM$K_GET_KEY and PSM$K_ 
POSITION_TO_KEY allows the modified symbiont to perform the file- 
positioning functions specified by the DCL commands START/QUEUE 
/FORWARD, START/QUEUE/ALIGN, START/QUEUE/TOP_OF_FILE, 
START/QUEUE/SEARCH, and START/QUEUE/BACKWARD. These file 
positioning functions also depend on the job controller’s checkpointing 
capability for print jobs. 


Note that your input routine might be called with a marker string that 
was originally returned in a different process context from the current 
one. This can occur because marker strings are sometimes stored in the 
queue-data file across system shutdowns or different invocations of your. 
symbiont. 


The funcdesc argument specifies the address of a string descriptor. Your 
routine must return the marker string by way of this argument. Digital 
recommends that you use one of the Run-Time Library string routines to 
copy the marker string to the descriptor. 


The symbiont periodically calls your input routine with the PSM$K_ 
GET_KEY function code when the symbiont wants to save a marker to a 
particular input record. 


PSM$K_OPEN 

When the symbiont calls your routine with this function code, your routine 
should prepare for input operations by performing such tasks as allocating | 
necessary resources, initializing storage areas, opening an input file, and 

so on. Typically, the next time the symbiont calls your input routine, the 
symbiont will specify the PSM$K_READ function code. Note, however, 

that under some circumstances the symbiont might follow an OPEN call 
immediately with a CLOSE call. 


The funcdese argument points to the name of the file to be opened. Your 
routine can use this file specification or the file identifcation to open the 
file. 


The funcarg argument specifies the address of a longword. Your input 
routine must return, in this longword, the carriage control type that is to 
be applied to the input records that your input routine will provide. 


The symbiont formatting routine requires this information to determine 
where to apply leading and trailing carriage control characters to the input 
records that your input routine will provide. 
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The $PSMDEF macro defines the following four carriage control types: 


Carriage Type Description 


‘PSM$K_CC_IMPLIED Implied carriage control. For this type, the symbiont 
inserts a leading linefeed (LF) and trailing carriage 
return (CR) in each input record. This is the default 
carriage control type; it is used if your routine does not 
supply a carriage control type in the funearg argument 
in response to the PSM$K_OPEN function call. 


PSM$K_CC_FORTRAN FORTRAN carriage control. For this type, the symbiont 
extracts the first byte of each input record and interprets 
the byte as a FORTRAN carriage control character, 
which it then applies to the input record. 


PSM$K_CC_PRINT PRN carriage control. For this type, the symbiont 
generates carriage control from a 2-byte record header 
that your input routine supplies, with each READ call, in 
the funearg argument. The funcarg argument specifies 
the address of a longword to receive this two-byte header 
record, which appears only in PRN print files. 


PSM$K_CC_INTERNAL Embedded carriage control. For this type, the symbiont 
supplies no carriage control to input records. Carriage 
control is assumed to be embedded in the input records. 


PSM$K_POSITION_TO_KEY 

When the symbiont calls your routine with this function code, your routine 
must locate the point in the input stream designated by the marker string 
that your routine returned to the symbiont on the PSM$K_GET_KEY 
function call. 


The next time the symbiont calls your routine, the symbiont specifies the 
PSM$K_READ function call, expecting to receive the next sequential input 
record. After rereading this record, subsequent READ calls proceed from 
this new position of the file. This is not a one-time rereading of a single 
record but a repositioning of the file. The symbiont calls your routine with 
this function code when the job controller receives a request to resume 
printing at a particular page. . 


Refer to the description of the PSM$K_GET_KEY for more information. 


PSM$K_READ 

When the symbiont calls your routine with this function code, your routine 
must return an input record. The symbiont repeatedly calls your input 
routine with the PSM$K_READ function code until (1) your routine 
indicates end of input by returning the status PSM$_EOF, (2) your 
routine or another routine returns an error status, or (3) the symbiont 
receives an asynchronous task-abortion request from the job controller. 


The funcdesc argument specifies the address of a string descriptor. Your 
routine must return the input record by using this argument. Digital 
recommends that you use one of the Run-Time Library string routines to 
copy the input record to the descriptor. 
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The funcarg argument specifies the address of a longword. This argument 
is used only if the carriage control type returned by your input routine on 
the PSM$K_OPEN function call was PSM$K_CC_PRINT. In this case, 
your input routine must supply, in the funcarg argument, the 2-byte 
record header found at the beginning of each input record. 


PSM$K_REWIND 

When the symbiont calls your routine with this function code, your routine 
must do one of two things: (1) return PSM$_FUNNOTSUP (function not 
supported) or (2) locate the point in the input stream designated as the 
beginning of the file. 


If your routine returns PSM$_FUNNOTSUP to this function code, then 
the symbiont subsequently calls your input routine with a PSM$K_ 
CLOSE function call followed by a PSM$K_OPEN function call. By 
returning PSM$_FUNNOTSUP, your routine is choosing not to support 
the repositioning of the input service to the beginning of the file. The 
symbiont, therefore, performs the desired function by closing and then 
reopening the input routine. 


You cannot use the funcdesc and the funcarg arguments with this 
function code. 


This function call allows the modified symbiont to perform the 
file-positioning functions specified by the DCL commands START 
/QUEUVE/TOP_OF_FILE, START/QUEUE/FORWARD, START/QUEUE 
/BACKWARD, START/QUEUE/SEARCH, and START/QUEUE/ALIGN. 
This is a required repositioning of the file. 


Other Input Function Codes 

The symbiont can call your input routine with other function codes. 
Your routine must return the status PSM$_FUNNOTSUP (function not 
supported) when it is called with any of the following function codes 
or with any undocumented function code. When the status PSM$_ 
FUNNOTSUP is returned, the symbiont performs its normal action as 
if no input routine were supplied. To suppress the symbiont’s normal 
action, you should return SS$_NORMAL. 


PSM$K_START_STREAM PSM$K_STOP_STREAM 
PSM$K_START_TASK PSM$K_PAUSE_TASK 
PSM$K_RESUME_TASK PSM$K_STOP_TASK 


PSM$K_RESET_STREAM 


These function codes correspond to message items, which are discussed in 
detail in Section 11.3.5, sent by the job controller to the symbiont. 


Other function codes correspond to internal symbiont mechanisms that are 
not part of the public interface to the print symbiont. 


Your input routine should return the status PSM$_FUNNOTSUP or SS$_ 
NORMAL when it is called with a message function code or with a private 
function code. 


funcdesc 

VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
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Function descriptor supplying information related to the function specified 
by the func argument. The funcdesc argument is the address of this 
descriptor. 


The contents of the function descriptor vary for each function. Refer to the 
description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 


funcarg 


VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Function argument supplying information related to the function specified 
by the func argument. The funcarg argument is the address of a 
longword containing this function argument. This argument can be an 
input or an output argument, depending on the function request, but is 
usually used as an output argument. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL Successful completion. The user input routine has 
completed the function that the symbiont requested. 
PSM$_FLUSH Flush output stream. The user input routine can 


return this status only when called with the PSM$K_ 
READ function code. When this status is returned 
to the symbiont, the symbiont stops calling the input 
routine with the PSM$K_READ function code until 
all outstanding format and output operations have 
completed. 


PSM$_FUNNOTSUP Function not supported. The user input routine 
does not support or does not recognize the function 
code supplied by the symbiont. To ensure future 
compatibility, your input routine should return this 
status for any unrecognized status codes. 


PSM$_PENDING Requested function accepted but not completed. 
Your input routine can return this status only with 
the PSM$K_READ function call. Further, if your 
routine returns PSM$_PENDING, your routine must 
eventually signal completion via the PSM$REPORT 
routine. Refer to the description of the PSM$REPORT 
routine for more information about asynchronous 
operations and the PSM$_PENDING condition value. 


This routine also returns any error condition values that you have coded 
your format routine to return. Refer to Section 11.3.1 for more information 
about error condition values. 
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USER-OUTPUT-ROUTINE Invoke User-Written 
Output Routine 
The user-written USER-OUTPUT-ROUTINE performs output operations. You 


supply a user output routine by calling the PSM$REPLACE routine with the 
routine code PSM$K_OUTPUT. 








FORMAT USER-OUTPUT-ROUTINE request_id ,work_area 
,func ,funcdesc ,funcarg 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ request_id 

. VMS usage: address 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Request identifier value supplied by the symbiont when it calls your 
output routine. The request_id argument is the address of a longword 
containing this value. 


If your output routine initiates an asynchronous operation (for example, 
a call to the Queue I/O Request (SYS$QIO) system service), you must 
save the request_id argument because you will need to store the request 
identifier value for later use with the PSM$REPORT routine. See the 
description of the PSM$REPORT routine for more information. 


work_area 


VMS usage: address 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Work area supplied by the symbiont for the use of your format routine. 
The symbiont supplies the address of this area when it calls your routine. 
The work_area argument is a longword containing the address of the 
work area. The work area is a section of memory that your format routine 
can use for buffering and other internal operations. 


The size of the work area allocated is specified by the work_size argument 
in the PSM$PRINT routine. If you do not specify work_size in the call to 
PSM$PRINT, no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each 
- thread. This work area is shared by all user routines. The work area is 
initialized to zero when the symbiont is first started. 


func 

VMS usage: function_code 

type: longword (unsigned) 
access: read only 


mechanism: by reference 
Function code supplied by the symbiont when it calls your output routine. 
The func argument is the address of a longword containing this code. 


The function code specifies the reason the symbiont is calling your output 
routine or, in other words, the function that the symbiont expects your 
routine to perform at this time. 


Most function codes require or allow additional information to be passed 

in the call via the funcdese and funcarg arguments. The description of 
each output function code, therefore, includes a description of how these 

two arguments are used for that function code. 


The following list describes all the function codes that the symbiont might 
supply when it calls your output routine (function codes applicable only to 
input and formatting routines are explained in the descriptions of the user 
input routine and user formatting routine, respectively); all function codes 
are defined by the $PSMDEF macro. 


Function Codes for Output Routines 


PSM$K_OPEN 

When the symbiont calls your output routine with this function code, your 
routine should prepare to move data to the device by performing such 
tasks as allocating the device, assigning a channel to the device, and so 
on. The next time the symbiont calls your output routine, the symbiont 
specifies one of the WRITE function codes (PSM$K_WRITE or PSM$K_ 
WRITE_NOFORMAT). 


The symbiont calls your output routine with the PSM$K_OPEN function 
code when the symbiont receives the SMBMSG$K_START_STREAM 
message from the job controller. 


If your output routine returns an error condition value (low bit clear) to 
the PSM$K_OPEN function call, the job controller stops processing on 
the stream and reports the error to whomever entered the DCL command 
START/QUEUE. 


The funcdese argument is the address of a descriptor that identifies the 
name of the device the output routine is to write to. This device name is 
established by the DCL command INITIALIZE/QUEUE/ON=device-name. 


The funcarg argument is the address of a longword into which the user 
output routine returns the device status longword. For the contents of 
the device status longword, refer to the description of the SMBMSG$K_ 
DEVICE_STATUS item in the SMB$READ_MESSAGE_ITEM routine, 
which is documented in Chapter 12. 
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Your output routine sets bits in the device status longword to indicate 
to the job controller whether the device falls into one of the following 
categories: 


¢ Can print lowercase letters 
e §6Is a terminal 


¢ Is connected to the CPU by means of a modem (remote) 


If your output routine does not set any of these bits in the device status 
longword, the job controller assumes, by default, that the device is a line 
printer that prints only uppercase letters. 


PSM$K_WRITE 

When the symbiont calls your routine with this function code, your routine 
must write data to the device. The symbiont supplies the data to be 
written in the funcdesc argument. Digital recommends that you use one 
of the Run-Time Library string routines to access the data in the buffer 
described by the funcdesc argument. 


PSM$K_WRITE_NOFORMAT 
When the symbiont calls your routine with this function code, your routine 


must write data to the device and must indicate to the device driver that 
the data is not to be formatted. 


The symbiont calls your routine with this function code when (1) the print 
request specifies the PASSALL option or (2) data is introduced by the 
ANSI DCS (device control string) escape sequence. 


The symbiont supplies the data to be written in the funcdesc argument. 
Digital recommends that you use one of the Run-Time Library string 
routines to move the data from the descriptor to the device. 


The output routine of the symbiont informs the device driver not to format 
the data in the following way: 


e When the device is a line printer, the symbiont’s output routine 
specifies the IO$_WRITEPBLK function code when it calls the $QIO 
system service. 


¢ When the device is a terminal, the symbiont’s output routine specifies 
the IO$¢M_NOFORMAT function modifier when it calls the $QIO 
system serivce. 


PSM$K_CANCEL 
When the symbiont calls your routine with this function code, your routine 
must abort any outstanding asynchronous I/O requests. 


The output routine supplied by the symbiont aborts outstanding I/O 
requests by calling the $CANCEL system service with the IO$_CANCEL 
function code. 
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If your output routine returned the condition value PSM$_PENDING to 
one or more previous write requests that are still outstanding (that is, 
PSM$REPORT has not yet been called to report completion), then your 
output routine must call PSM$REPORT one time for each outstanding 
write request that is canceled with this call. That is, canceling an 
asynchronous write request does not relieve the user output routine of 
the requirement to call PSM$REPORT once for each asynchronous write 
request. 


You cannot use the funcdesc and funcarg arguments with this function 
code. 


PSM$K_CLOSE 

When the symbiont calls your routine with this function code, your output 
routine must terminate processing and release any resources it allocated 
(for example, channels assigned to the device). 


You cannot use the funcdese and funcarg arguments with this function 
code. 


Other Output Function Codes 

The symbiont can call your output routine with other function codes. 
Your routine should return the status PSM$_FUNNOTSUP (function not 
supported) when it is called with any of the following function codes 

or with any undocumented function code. When the status PSM$_ 
FUNNOTSUP is returned, the symbiont performs its normal action as 
if no output routine were supplied. To suppress the symbiont’s normal 
action, you should return SS$_NORMAL. 


PSM$K_START_STREAM PSM$K_STOP_STREAM 
PSM$K_START_TASK PSM$K_PAUSE_TASK 
PSM$K_RESUME_TASK PSM$K_STOP_TASK 


PSM$K_RESET_STREAM 


These function codes correspond to message items, which are discussed in 
more detail in Section 12.1.6, sent by the job controller to the symbiont. 


Other function codes correspond to internal symbiont mechanisms that are 
not part of the public interface to the print symbiont. 


Your output routine should return the status PSM$_FUNNOTSUP or 
SS$_NORMAL when it is called with a message function code or with a 
private function code. 


funcdesc 


VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Function descriptor supplying information related to the function specified 
by the func argument. The funcdesc argument is the address of this 
descriptor. 


The contents of the function descriptor vary for each function. Refer to the 
description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 
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funcarg 
VMS usage: user_arg 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Function argument supplying information related to the function specified 
by the fune argument. The funcarg argument is the address of a 
longword containing this function argument. 


The contents of the function argument vary for each function. Refer to the 
description of each function code to determine the contents of the function 
argument. In some cases, the function argument is not used. 





CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL Successful completion. The user output routine has 
completed the function that the symbiont requested. 
PSM$_FUNNOTSUP Function not supported. The user output routine 


does not support or does not recognize the function 
code supplied by the symbiont. To ensure future 
compatibility, your output routine should return this 
status for any unrecognized status codes. 


PSM$_PENDING Requested function accepted but not completed. 
Your output routine can return this status only with 
PSM$K_WRITE and PSM$K_WRITE_NOFORMAT 
function calls. Further, if your routine returns PSM$_ 
PENDING, your routine must eventually signal 
completion by way of the PSM$REPORT routine. 
Refer to the description of the PSM$REPORT 
routine for more information about asynchronous 
write operations and the PSM$_PENDING condition 
value. 


This routine also returns any error condition values that you have coded 
your output routine to return. Refer to Section 11.3.1 for more information 
about error condition values. 
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The Symbiont/Job Controller Interface (SMB) routines provide the 
interface between the job controller and symbiont processes. A user- 
written symbiont must use these routines to communicate with the VMS 
job controller. 





12.1 Introduction to SMB Routines 


Always use the SMB interface routines or the SYS$SNDJBC or 
SYS$GETQUI system services to communicate with the job controller. 
You need not and should not attempt to communicate directly with the job 
controller. 


To write your own symbiont, you need to understand how symbionts work 
and, in particular, how the standard VMS print symbiont behaves. 


12.1.1 Types of Symbiont 


There are two types of symbiont: 


Device symbiont, either an input symbiont or an output symbiont. 

An input symbiont is one that transfers data from a slow device to 

a fast device, for example, from a card reader to a disk. A card- 
reader symbiont is an input symbiont. An output symbiont is one that 
transfers data from a fast device to a slow device, for example, from a 
disk to a printer or terminal. A print symbiont is an output symbiont. 


Server symbiont, a symbiont that processes or transfers data but is 
not associated with a particular device; one example is a symbiont that 
transfers files across a network. 


The VMS operating system does not supply any server symbionts. 


12.1.2 Symbionts Supplied with the VMS Operating System 
The VMS operating system supplies two symbionts: 


SYS$SYSTEM:PRTSMB.EXE (PRTSMB for short), an output symbiont 
for use with printers and printing terminals. 


PRTSMB performs such functions as inserting flag, burst, and trailer 
pages into the output stream; reading and formatting input files; and 
writing formatted pages to the printing device. 


You can modify PRTSMB using the Print Symbiont Modification (PSM) 
routines. 


SYS$SYSTEM:INPSMB.EXE (INPSMB for short) an input symbiont 
for use with card readers. 
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This symbiont handles the transferring of data from a card reader to 
a disk file. You cannot modify INPSMB, nor can you write an input 
symbiont using the SMB routines. 


12.1.3. Symbiont Behavior in the VMS Environment 
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In the VMS environment, a symbiont is a process under the control of the 
VMS job controller that transfers or processes data. 


Figure 12—1 depicts the VMS components that take part in the handling 
of user requests that involve symbionts. This figure shows two symbionts: 
(1) the print symbiont supplied by the VMS operating system, PRTSMB, 
and (2) a user-written symbiont, GRAPHICS.EXE, which services a 
graphics plotter. The numbers in the figure correspond to the numbers in 
the list that follows. 


This list does not reflect the activities that must be performed by the 
hypothetical, user-written symbiont, GRAPHICS.EXE. This symbiont is 
represented in the figure to illustrate the correspondence between a user- 
written symbiont and the print symbiont supplied by the VMS operating 
system. 


Although SMB routines can be used for a diiferent kind of symbiont, many 
of their arguments and associated symbols have names related to the print 
symbiont. The print symbiont is presented here as an example of a typical 
symbiont and illustrates points that are generally true for symbionts. 


@ You request a printing job with the DCL command PRINT. DCL calls 
the Send to Job Controller (SYS$SNDJBC) system service, passing the 
name of the file to be printed to the job controller, along with any other 
information specified by qualifiers for the PRINT command. 


@ The job controller places the print request in the appropriate queue 
and assigns the request a job number. 


© The job controller breaks the print job into a number of tasks (for 
example, printing three copies of the same file is three separate tasks). 
The job controller makes a separate request to the symbiont for each 
task. 


Each request that the job controller makes consists of a message. Each 
message consists of a code that indicates what the symbiont is to do 
and a number of items of information that the symbiont needs to carry 
out the task (the name of the file, the name of the user, and so on.) 


@ PRTSMB interprets the information it receives from the job controller. 


© PRTSMB locates and opens the file it is to print by using the file- 
identification number the job controller specified in the start-task 
message. 


@ PRTSMB sends the data from the file to the printer’s driver. 
@ The device driver sends the data to the printer. 
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Figure 12-1 Symbionts in the VMS Operating System Environment 
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12.1.4 Writing a Symbiont 


Writing your own symbiont permits you to use the queueing mechanisms 
and control functions of the VMS job controller. You might want to do this 
if you need a symbiont for a device that cannot be served by PRTSMB (or a 
modified form of PRTSMB) or if you need a server symbiont. The interface 
between the job controller and the symbiont permits the symbiont you 
write to use the many features of the job controller. 


For example, when you use the DCL command PRINT to print a file, 
the job controller sends a message to the print symbiont telling it to 
print the file. However, when a user-written symbiont receives the same 
message (caused by entering a PRINT command), it might interpret 

it to mean something quite different. A robot symbiont, for example, 
might interpret the message as a command for movement and the 

file specification (specified with the PRINT command) might be a file 
describing the directions in which the robot is to move. 
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Note: Modifying PRTSMB is easier than writing your own symbiont; 
choose this option if possible. The Print Symbiont Modification 
(PSM) routines describe how to modify PRTSMB to suit your 
needs. 


12.1.5 Guidelines for Writing a Symbiont 


Although you can write a symbiont to use the queuing mechanisms and 
other features of the job controller in whatever way you want, you must 
follow these guidelines to ensure that your symbiont works correctly: 
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The symbiont must not use any of the process-permanent channels, 
which are assigned to the following logical names: 


— SYS$INPUT 

- SYS$OUTPUT 

— SYS$ERROR 

—- SYS$COMMAND 


The symbiont must allocate and deallocate memory using the RTL 
routines LIB$GET_VM and LIB$FREE_VM. 


To be compatible with future releases of the VMS operating system, 
you should write the symbiont to ignore unknown message-item codes 
and unknown message-request codes. (See the SMB$READ_ITEM_ 
MESSAGE routine.) 


The symbiont must communicate with the job controller by using the 
Job-Controller/Symbiont Interface (SMB) routines, the SYS$SNDJBC 
system service, and the SYS$GETQUI system service. 


The symbiont should not perform lengthy operations within the context 
of an AST routine. The symbiont can only receive messages from the 
job controller when it is not executing within the context of an AST 
routine. 


The symbiont code should be linked against SMBSRVSHR.EXE in 
order to define the SMB routine address and the following status 
codes: 


— SMB$_INVSTMNBR 
— SMB$_INVSTRLEV 
— SMB$_NOMOREITEMS 


To assign a symbiont to a queue after it is compiled and linked, the 
executable image of the symbiont must reside in SYS$SYSTEM, and 
you must enter either of the following commands: 
INITIALIZE/QUEUE/PROCESSOR=symbiont_filename 
START/QUEUE/PROCESSOR=symbiont_filename 

You should specify only the file name in the command. The disk and 


directory default to SYS$SYSTEM, and all fields except the file name 
are ignored. 
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¢ To help debug symbionts, you should define the logical names 
DBG$INPUT and DBG$OUTPUT in the LNM$GROUP_000001 logical 
name table to point to your debugging terminal. 


12.1.6 The Symbiont/Job-Controller Interface Routines 


The five SMB routines form a public interface to the VMS job controller. 
The job controller delivers requests to symbionts by means of this 
interface, and the symbionts communicate their responses to those 
requests through this interface. A user-written symbiont uses the 
following routines to exchange messages with the job controller: _ 


SMBSINITIALIZE Initializes the SMB facility’s internal database, 
establishes the interface to the job controller, and 
defines whether 


* Messages from the job controller are to be 
delivered to the symbiont synchronously or 
asynchronously with respect to execution of 
the symbiont. 

« The symbiont is to be single-threaded or 
multithreaded; these concepts are described 
in the sections that follow. 


SMB$CHECK_FOR_MESSAGE Checks to see if a message from the job 
controller to the symbiont has arrived (used 
with synchronous symbionts) 


SMB$READ_MESSAGE Reads the job controller’s message into a buffer 


SMB$READ_MESSAGE_ITEM Returns one item of information from the job 
controller’s message (which can have several 
informational items) 

SMB$SEND_TO_JOBCTL Sends a message from the symbiont to the job 
controller 


The following sections discuss how to use the SMB routines when writing 
your symbiont. 


12.1.7 Choosing the Symbiont Environment 


The first SMB routine that a symbiont must call is the SMB$INITIALIZE 
routine. In addition to allocating and initializing the SMB facility’s 
internal database, it offers you two options for your symbiont environment: | 
synchronous or asynchonous delivery of messages from the job controller 
and single streaming or multistreaming the symbiont. 


12.1.7.1 Synchronous Versus Asynchronous Delivery of Requests 
When you initialize your job controller/symbiont interface, the symbiont 
has the option of accepting requests from the job controller sychronously 
or asynchronously. 
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Synchronous Environment 


The address of an AST routine is an optional argument to the 
SMBS$INITIALIZE routine; if it is not specified, the symbiont receives 
messages from the job controller synchronously. A symbiont that receives 
messages synchronously must call SMB$CHECK_FOR_MESSAGE 
periodically during the processing of tasks in order to ensure the timely 
delivery of STOP_TASK, PAUSE_TASK, and RESET_STREAM requests. 


SMB$CHECK_FOR_MESSAGE checks to see if a message from the 

job controller is waiting. If a message is waiting, SMB$CHECK_FOR_ 
MESSAGE returns a success code. The caller of SMB$CHECK_FOR_ 
MESSAGE can then call SMB$READ_MESSAGE to read the message and 
take the appropriate action. 


If no message is waiting, SMB$CHECK_FOR_MESSAGE returns a zero in 
RO. The caller of SMB$CHECK_FOR_MESSAGE can continue to process 
the task at hand. 


Figure 12-2 is a flowchart for a synchronous, single-threaded symbiont. 
The flowchart does not show all the details of the logic the symbiont needs 
and does not show how the symbiont handles Pause-task, Resume-task, or 
Reset-stream requests. 


Asynchronous Environment 


To receive messages asynchronously, a symbiont specifies a message- 
handling AST routine as the second argument to the SMB$INITIALIZE 
routine. In this scheme, whenever the job controller sends messages to the 
symbiont, the AST routine is called. 


The AST routine is called with no arguments and returns no value. You 
have the option of having the AST routine read the message within the 
context of its execution or of having the AST routine wake a suspended 
process to read the message outside the context of the execution of the 
AST routine. 


Be aware that an AST can be delivered only while the symbiont is not 
executing within the context of an AST routine. Thus, in order to ensure 
delivery of messages from the job controller, the symbiont should not 
perform lengthy operations at AST level. 


This is particularly important to the execution of STOP_TASK, PAUSE_ 
TASK, and RESET_STREAM requests. If a STOP_TASK request cannot 
be delivered during the processing of a task, for example, it is useless. 


One technique that ensures delivery of STOP and PAUSE requests in an 
asynchronous environment is to have the AST routine set a flag if it reads 
a PAUSE_TASK, STOP_TASK, or a RESET_STREAM request and to have 
the symbiont’s main routine periodically check the flag. 


Figure 12-3 and Figure 12—4 show a logic chart for a single-threaded, 
asynchronous symbiont. The figures do not show many details that your 
symbiont might include, such as a call to the $QIO system service. 
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Figure 12-2 Flowchart for a Single-Threaded, Synchronous Symbiont 
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Note that the broken lines in Figure 12—3 that connect the calls to 
SYS$HIBER with the AST routine’s calls to SYS$WAKE show that the 
next action to take place is the call to SYS$WAKE. They do not accurately 
represent the flow of control within the symbiont but represent the action 
of the job controller in causing the AST routine to execute. 
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Figure 12-3 Flow Chart for a Single-Threaded, Asynchronous Symbiont (MAIN Routine) 
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Figure 12-4 Flow Chart for a Single-Threaded, Asynchronous Symbiont (AST Routine) 
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12.1.7.2 Single-Streaming Versus Multistreaming 
A single-stream (or thread) is a logical link between a queue and a 
symbiont process. When a symbiont process is linked to more than 
one queue and serves those queues simultaneously, it is called a 
multithreaded symbiont. 
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The argument to the SMB$READ_MESSAGE routine provides a way for 
a multithreaded symbiont to keep track of the stream referred to by a 
request. Writing your own multithreaded symbiont, however, can be a 
complex undertaking. 


12.1.8 Reading Job Controller Requests 


There are seven general functions that the job controller can request of the 
symbiont: 


SMBMSG$K_START_STREAM SMBMSG$K_STOP_STREAM 
SMBMSG$K_START_TASK SMBMSG$K_PAUSE_TASK 
SMBMSG$K_RESUME_TASK SMBMSG$K_STOP_TASK 


SMBMSG$K_RESET_STREAM 


The job controller passes these requests to the symbiont in a structure 
that contains (1) a code that identifies the requested function and (2) 
optional items of information that the symbiont might need to perform the 
requested function. 


By calling SMB$READ_MESSAGE, the symbiont reads the function code 
and writes the associated items of information, if any, into a buffer. The 
symbiont then parses the message items stored in the buffer by calling the 
SMB$READ_MESSAGE_ITEM routine. SMB$READ_MESSAGE_ITEM 
reads one message item each time it is called. 


Each message item consists of a code that identifies the type of 
information the item contains, and the information itself. For example, the 
SMBMSG$K_JOB_NAME code tells the symbiont that the item contains a 
string, which is the name of a job. 


The number of message items in a request message varies with each 
type of request. Therefore, to ensure that all message items are read, 
SMB$READ_MESSAGE_ITEM must be called repeatedly for each request. 
SMB$READ_MESSAGE_ITEM returns status SMB$_NOMOREITEMS 
after it has read the last message item in a given request. 


Typically, a symbiont checks the code of a message item against a case 
table and stores the message string in an appropriate variable until all the 
message items are read and the processing of the request can begin. 


See the description of the SMB$READ_MESSAGE_ITEM routine for a 
table that shows the message items that make up each type of request. 


12.1.9 Processing Job Controller Requests 
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After a request is read, it must be processed. The way a request is 
processed depends on the type of request. The following section lists, 

for each request that the job controller sends to the print symbiont, the 
actions that the standard symbiont (PRTSMB) takes when the message is 
received. These actions are oriented toward print symbionts in particular 
but can serve as a guideline for other kinds of symbionts as well. 
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The symbiont you write can respond to requests in a similar way or in 

a different way appropriate to the function of your symbiont. Digital 
suggests that your routines follow the guidelines described in this 
document. (Note that the behavior of the standard symbiont is subject 
to change without notice in future versions of the VMS operating system.) 


SMBMSG$K_START_STREAM 


¢ Reset all stream-specific information that might have been altered by 
previous START_STREAM requests on this stream (for multithreaded 
symbionts). 


¢ Read and store the message items associated with the request. 


e Allocate the device specified by the SMBMSG$K_DEVICE_NAME 
item. 


e Assign a channel to the device. 
¢ Obtain the device characteristics. 


e Ifthe device is neither a terminal nor a printer, then abort processing 
and return an error to the job controller by means of the SMB$SEND_ 
TO_JOBCTL routine. Note that, even though an error has occurred, 
the stream is still considered started. The job controller detects the 
error and sends a STOP_STREAM request to the symbiont. 


¢ Set temporary device characteristics suited to the way the symbiont 
will use the device. 


¢ For remote devices (devices connected to the system by means of a 
modem) establish an AST to report loss of the carrier signal. 


¢ Report to the job controller that the request has been completed 
and that the stream is started, by specifying SMBMSG$K_START_ 
STREAM in the call to SMB$SEND_TO_JOBCTL. 
SMBMSG$K_START_TASK 


¢ Reset all task-specific information that might have been altered by 
previous START_TASK requests on this stream number. 


e¢ Read and store the message items associated with the request. 
¢ Open the main input file. 


¢ Report to the job controller that the task has been started by specifying 
SMBMSG$K_START_TASK in the call to the SMB$SEND_TO_ 
JOBCTL routine. 


¢ Begin processing the task. 


¢ When the task is complete, notify the job controller by specifying 
SMBMSG$K_TASK_COMPLETE in the call to the SMB$SEND_TO_ 
JOBCTL routine. 
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SMBMSG$K_PAUSE_TASK 


Read and store the message items associated with the request. 


Set a flag that will cause the main processing routine to pause at the 
beginning of the next output page. 


When the main routine pauses, notify the job controller by specifying 
SMBMSG$K_PAUSE_TASK in the call to the SMB$SEND_TO_ 
JOBCTL routine. 


SMBMSG$K_RESUME_TASK 


Read and store the message items associated with the request. 
Perform any positioning functions specified by the message items. 


Clear the flag that causes the main input routine to pause, and resume 
processing the task. 


Notify the job controller that the task has been resumed by specifying 
SMBMSG$K_RESUME_TASK in the call to the SMB$SEND_TO_ 
JOBCTL routine. 


SMBMSG$K_STOP_TASK 


Read and store the message items associated with the request. 
If processing of the current task has paused, then resume it. 
Cancel any outstanding I/O operations. 

Close the input file. 


If the job controller specified, in the START_TASK message, that 

a trailer page should be printed when the task is stopped or if it 
specified that the device should be reset when the task is stopped, then 
perform those functions. 


Notify the job controller that the task has been stopped abnormally by 
specifying SMBMSG$K_STOP_TASK and by specifying an error vector 
in the call to SMB$SEND_TO_JOBCTL. PRTSMB specifies the value 
passed by the job controller in the SMBMSG$K_STOP_CONDITION 
item as the error condition in the error vector. 


SMBMSG$K_STOP_STREAM 


Read and store the message items associated with the request. 


Release any stream-specific resources: (1) deassign the channel to the 
device, and (2) deallocate the device. 


Notify the job controller that the stream has been stopped by 
specifying SMBMSG$K_STOP_STREAM in the call to SMB$SEND_ 
TO_JOBCTL. 


If this is a single-threaded symbiont or if this is a multithreaded 
symbiont but all other streams are currently stopped, then call the 
SYS$EXIT system service with the condition code SS$_NORMAL. 
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SMBMSG$K_RESET_STREAM 
e Read and store the message items associated with the request. 


¢ Abort any task in progress—you do not need to notify the job controller 
that the task has been aborted, but you can do so if you want. 


¢ If the job controller specified, in the START_TASK message, that 
a trailer page should be printed when the task is stopped or if it 
specified that the device should be reset when the task is stopped, then 
suppress those functions. 


The job controller sends the symbiont a RESET_STREAM request 
to regain control of a queue or a device that has failed to respond to 
a STOP_TASK request. The RESET_STREAM request should avoid 
any further I/O activity if possible. The printer might be disabled, 
for example, and requests for output on that device will never be 
completed. 


¢ Continue as if this were a STOP_STREAM request. 


Note: A STOP_STREAM request and a RESET_STREAM request each 
stop the queue; but a RESET_STREAM request is an emergency 
stop and is used, for example, when the device has failed. A 
RESET_STREAM request should prevent any further I/O activity 
because the printer might not be able to complete it. 


12.1.10 Responding to Job Controller Requests 


The symbiont uses the SMB$SEND_TO_JOBCTL routine to send 
messages to the job controller. 


Most messages that the symbiont sends to the job controller are responses 
to requests made by the job controller. Such messages inform the 

job controller that the request has been completed successfully or 
unsuccessfully. The function code that the symbiont returns to the 
controller in the call to SMB$SEND_TO_JOBCTL indicates what request 
has been completed. 


For example, if the job controller sends a START_TASK request using 
the SMBMSG$K_START_TASK code, the symbiont responds by calling 
SMB$SEND_TO_JOBCTL using SMBMSG$K_START_TASK as the 
request argument to indicate that task processing has begun. Until 

the symbiont responds, the DCL command SHOW QUEUE indicates that 
the queue is starting. 


The responses to some requests use additional arguments to send more 
information than just the request code. See the SMB$SEND_TO_JOBCTL 
routine for a table showing the additional arguments allowed in response 
to each request. 


In addition to sending messages in response to requests, the symbiont can 
send other messages to the job controller. In these messages the symbiont 
sends either the SMBMSG$K_TASK_COMPLETE code, indicating that it 
has completed a task, or SMBMSG$K_TASK_STATUS, indicating that the 
message contains information on the status of a task. 


SMB-13 


12.2 


Symbiont/Job Controller Interface (SMB) Routines 
12.1 Introduction to SMB Routines 


Note that, when a START_TASK request is delivered, the symbiont 
responds with a SMB$SEND_TO_JOBCTL message with the 
SMBMSG$K_START_TASK code. This response means the task has 
been started. It does not mean the task has been completed. When the 
symbiont completes the task, it calls SMB$SEND_TO_JOBCTL with the 
SMBMSG$K_TASK_COMPLETE code. 





SMB Routines 


The following pages describe the individual SMB routines. 
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SMB$CHECK_FOR_MESSAGE Check for Message 
from Job Controller 


The SMBSCHECK_FOR_MESSAGE routine determines whether a message 
sent from the job controller to the symbiont is waiting to be read. 








FORMAT SMB$CHECK_FOR_MESSAGE 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS ~ None. 





DESCRIPTION When your symbiont calls the SMB$INITIALIZE routine to initialize the 
interface between the symbiont and the job controller, you can choose to 
have requests from the job controller delivered by means of an AST. If 
you choose not to use ASTs, your symbiont must call SMB$CHECK_FOR_ 
MESSAGE during the processing of tasks in order to see if a message 
from the job controller is waiting to be read. If a message is waiting, 
SMB$CHECK_FOR_MESSAGE returns a success code; if not, it returns a 
zero. 


If a message is waiting, the symbiont should call SMB$READ_MESSAGE 
to read it to determine if immediate action should be taken (as in the case 
of STOP_TASK, RESET_STREAM or PAUSE_TASK). 


If a message is not waiting, SMB$CHECK_MESSAGE returns a zero. If 
this condition is detected, the symbiont should continue processing the 
request at hand. 





Gi a SS$_ NORMAL One or more messages waiting. 
RETURNED 0 No messages waiting. 
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SMBSINITIALIZE Initialize User-Written Symbiont — 


The SMB$INITIALIZE routine initializes the user-written symbiont and the 
interface between the symbiont and the job controller. It allocates and 
initializes the internal databases of the interface and sets up the mechanism 
that is to wake up the symbiont when a message is received. 





FORMAT 


SMBSINITIALIZE _ structure_level [,ast_routine] 
[,streams] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 
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structure_level 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: — read only 

mechanism: by reference 

Version of the job-controller/symbiont interface. The structure_level 
argument is the address of a longword containing the version of the 
job-controller/symbiont interface used when the symbiont was compiled. 
Always place the value of the symbol SMBMSG$K_STRUCTURE_LEVEL 
in the longword addressed by this argument. This symbol is defined by the 
$SMBDEF macro. The $SMBDEF macro is defined in the macro library 
SYS$LIBRARY:LIB.MLB. 


ast_routine 

VMS usage: ast_procedure 

type: procedure entry mask 

access: read only 

mechanism: by reference 

Message-handling routine called at AST level. The ast_routine argument 
is the address of the entry point of the message-handling routine to be 
called at AST level when the symbiont receives a message from the job 
controller. The AST routine is called with no parameters and returns no 
value. If an AST routine is specified, the routine is called once each time 
the symbiont receives a message from the job controller. 


The AST routine typically reads the message and determines if immediate 
action must be taken. Be aware that an AST can be delivered only while 
the symbiont is operating at non-AST level. Thus, to ensure delivery of 
messages from the job controller, the symbiont should not perform lengthy 
operations at AST level. 
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The ast_routine argument is optional. If you do not specify it, the 
symbiont must call the SMB$CHECK_FOR_MESSAGE routine to check 
for waiting messages. 


streams 


VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Maximum number of streams the symbiont is to support. The streams 
argument is the address of a longword containing the number of streams 
that the symbiont is to support. The number must be in the range 1 to 32. 


If you do not specify this argument, a default value of 7 is used. Thus, 
by default, a symbiont supports one stream. Such a symbiont is called a 
single-threaded symbiont. 


A stream (or thread) is a logical link between a queue and a symbiont. 
When a symbiont is linked to more than one queue, and serves those 
queues simultaneously, it is called a multithreaded symbiont. 





DESCRIPTION 


Your symbiont must call SMB$INITIALIZE before calling any other SMB$ 
routines. It calls SMB$INITIALIZE in order to do the following: 


e Allocate and initialize the SMB$ facility's internal database. 
e Establish the interface between the job controller and the symbiont. 
¢ Determine the threading scheme of the symbiont. 


¢ Set up the mechanism to wake your symbiont when a message is 
received. 


After the symbiont calls SMB$INITIALIZE, it can communicate with the 
job controller using the other SMB$ services. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL Routine successfully completed. 
SMB$_INVSTRLEV Invalid structure level. 


This routine also returns any codes returned by $ASSIGN and 
LIB$GET_VM. 
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SMB$READ_MESSAGE Obtain Message Sent by 
Job Controller 


The SMB$READ_MESSAGE routine copies a message that the job controller 
has sent into the caller’s specified buffer. 








FORMAT SMB$READ_MESSAGE stream, buffer ,request 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _ stream 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 
Stream number specifying the stream to which the message refers. 
The stream argument is the address of a longword into which the job 
controller writes the number of the stream referred to by the message. In 
single-threaded symbionts, the stream number is always 0. 


buffer 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 

Address of the descriptor that points to the buffer into which the job 
controller writes the message. SMB$READ_MESSAGE uses the RTL 
STR$ string-handling routines to copy the message into the buffer you 
supply. The buffer should be specified by a dynamic string descriptor. 


request 

VMS usage: identifier 

type: longword (unsigned) 
access: write only 


mechanism: by reference 

Code that identifies the request. The request argument is the address 
of a longword into which SMB$READ_MESSAGE writes the code that 
identifies the request. 
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There are seven request codes. Each code is interpreted as a message by 
the symbiont. The codes and their descriptions follow: 


SMBMSG$K_START_STREAM Initiates processing on an inactive symbiont 
stream. The job controller sends this message 
when a START/QUEUE or an INITIALIZE/QUEUE 
/START command is issued on a stopped queue. 


SMBMSG$K_STOP_STREAM Stops processing on a started queue. The job 
controller sends this message when a STOP 
/QUEUE/NEXT command is issued, after the 
symbiont completes any currently active task. 


SMBMSG$K_RESET_STREAM Aborts all processing on a started stream and 
requeues the current job. The job controller 
sends this message when a STOP/QUEUE 
/RESET command is issued. 


SMBMSG$K_START_TASK Requests that the symbiont begin processing a 
task. The job controller sends this message when 
a file is pending on an idle, started queue. 


SMBMSG$K_STOP_TASK Requests that the symbiont abort the processing 
of a task. The job controller sends this message 
when a STOP/QUEUE/ABORT or STOP/QUEUE 
/REQUEUE command is issued. The item 
SMBMSG$K_STOP_CONDITION identifies 
whether this is an abort or a requeue request. 


SMBMSG$K_PAUSE_TASK Requests that the symbiont pause in the 
processing of a task but retain the resources 
necessary to continue. The job controller sends 
this message when a STOP/QUEUE command is 
issued without the /ABORT, /ENTRY, /REQUEUE, 
or /NEXT qualifier for a queue that is currently 
printing a job. 

SMBMSG$K_RESUME_TASK Requests that the symbiont continue processing a 
task that has been stopped with a PAUSE_TASK 
request. This message is sent when a START 
/QUEUE command is issued for a queue served 
by a symbiont that has paused in processing the 
current task. 





DESCRIPTION 


Your symbiont calls SMB$READ_MESSAGE to read a message that the 
job controller has sent to the symbiont. 


Each message from the job controller consists of a code identifying the 
function the symbiont is to perform and a number of message items. 
There are seven codes. Message items are pieces of information that the 
symbiont needs to carry out the requested function. 


For example, when you enter the DCL command PRINT, the job controller 
sends a message containing a START_TASK code and a message item 
containing the specification of the file to be printed. 


SMB$READ_MESSAGE writes the code into a longword (specified by the 
request argument) and writes the accompanying message items, if any, 
into a buffer (specified by the buffer argument). 
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See the description of the SMB$READ_MESSAGE_ITEM routine for 
information about processing the individual message items. 





CONDITION SS$_NORMAL Routine completed successfull 
VALUES . ee 

LIB$_INVARG Routine completed unsuccessfully because of an 
RETURNED invalid argument. 


This routine also returns any of the condition codes returned by the 
Run-Time Library string-handling (STR$) routines. 
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SMB$READ_ MESSAGE _ ITEM Parse Next Item from 


Message Buffer 


The SMB$READ_MESSAGE_ITEM routine reads a buffer that was filled in 
by the SMB$READ_MESSAGE routine, parses one message item from the 
buffer, writes the item’s code into a longword, and writes the item into a buffer. 





FORMAT 


SMB$READ_MESSAGE_ITEM message ,context 
,ltem_code , buffer 
[,size] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


message 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Message items that SMB$READ_MESSAGE_ITEM is to read. The 
message argument is the address of a descriptor of a buffer. The buffer 
is the one that contains the message items that SMB$READ_MESSAGE_ 
ITEM is to read. The buffer specified here must be the same as that 
specified with the call to the SMB$READ_MESSAGE routine, which fills 
the buffer with the contents of the message. 


context 


VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Value initialized to 0 specifying the first message item in the buffer 
to be read. The context argument is the address of a longword that 
the SMB$READ_MESSAGE_ITEM routine uses to determine the next 
message item to be returned. When this value is 0, it indicates that 
SMB$READ_MESSAGE_ITEM is to return the first message item. 


The SMB$READ_MESSAGE_ITEM routine updates this value each time 
it reads a message item. SMB$READ_MESSAGE_ITEM sets the value to 


0 when it has returned all the message items in the buffer. 


SMB-21 


Symbiont/Job Controller Interface (SMB) Routines 
SMB$READ_MESSAGE_ITEM 


item_code 

VMS usage: smb_item 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Item code specified in the message item that identifies its type. The item_ 
code argument is the address of a longword into which SMB$READ_ 
MESSAGE_ITEM writes the code that identifies what item it is returning. 


The codes that identify message items are defined at the end of the 
DESCRIPTION section for this routine. 


buffer 

VMS usage: char_string 
type: character string 
access: write only 


mechanism: by descriptor 

Message item. The buffer argument is the address of a descriptor of a 
buffer. The buffer is the one in which the SMB$READ_MESSAGE_ITEM 
routine is to place the message item data. SMB$READ_MESSAGE_ITEM 
uses the RTL STR$ string-handling routines to copy the message item 
data into the buffer. 


size 

VMS usage: word_unsigned 
type: word (unsigned) 
access: write only 


mechanism: by reference 

Size of the message item. The size argument is the address of a word in 
which the SMB$READ_MESSAGE_ITEM is to place the size, in bytes, of 
the item’s data. 
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The job controller can request seven functions from the symbiont. They 
are identified by the following codes: 


SMBMSG$K_START_STREAM SMBMSG$K_STOP_STREAM 
SMBMSG$K_START_TASK SMBMSG$K_PAUSE_TASK 
SMBMSG$K_RESUME_TASK SMBMSG$K_STOP_TASK 


SMBMSG$K_RESET_STREAM 


The job controller passes the symbiont a request containing a code and, 
optionally, a number of message items containing information the symbiont 
might need to perform the function. The code specifies what function 

the request is for, and the message items contain information that the 
symbiont needs to carry out the function. 


By calling SMB$READ_MESSAGE, the symbiont reads the request 
and writes the message items into the specified buffer. The symbiont 
then obtains the individual message items by calling the SMB$READ_ 
MESSAGE_ITEM routine. 


Each message item consists of a code that identifies the information the 
item represents, and the item itself. For example, the SMB$K_JOB_ 
NAME code tells the symbiont that the item specifies a job’s name. 
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The number of items in a request varies with each type of request. 
Therefore, you must call SMB$READ_MESSAGE_ITEM repeatedly for 
each request to ensure that all message items are read. Each time 
SMB$READ_MESSAGE_ITEM reads a message item, it updates the 
value in the longword specified by the context argument. SMB$READ_ 
MESSAGE_ITEM returns the code SMB$_NOMOREITEMS after it has 


read the last message item. 


The following table shows the message items that can be delivered with 


each request: 


Request 


SMBMSG$K_START_TASK 


Message Item 


SMBMSG$K_ACCOUNT_NAME 
SMBMSG$K_AFTER_TIME 
SMBMSG$K_BOTTOM_MARGIN 
SMBMSG$K_CHARACTERISTICS 
SMBMSG$K_CHECKPOINT_DATA 
SMBMSG$K_ENTRY_NUMBER 
SMBMSG$K_FILE_COPIES 
SMBMSG$K_FILE_COUNT 
SMBMSG$K_FILE_IDENTIFICATION 
SMBMSG$K_FILE_SETUP_MODULES 
SMBMSG$K_FILE_SPECIFICATION 
SMBMSG$K_FIRST_PAGE 
SMBMSG$K_FORM_LENGTH 
SMBMSG$K_FORM_NAME 
SMBMSG$K_FORM_SETUP_MODULES 
SMBMSG$K_FORM_WIDTH 
SMBMSG$K_JOB_COPIES 
SMBMSG$K_JOB_COUNT 
SMBMSG$K_JOB_NAME 
SMBMSG$K_JOB_RESET_MODULES 
SMBMSG$K_LAST_PAGE 
SMBMSG$K_LEFT_MARGIN 
SMBMSG$K_MESSAGE_VECTOR 
SMBMSG$K_NOTE 
SMBMSG$K_PAGE_SETUP_MODULES 
SMBMSG$K_PARAMETER_1 


SMBMSG$K_PARAMETER_8 
SMBMSG$K_PRINT_CONTROL 
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Note: 


Request Message Item 


SMBMSG$K_SEPARATION_CONTROL 
SMBMSG$K_REQUEST_CONTROL 
SMBMSG$K_PRIORITY 
SMBMSG$K_QUEUE 
SMBMSG$K_RIGHT_MARGIN 
SMBMSG$K_TIME_QUEUED 
SMBMSG$K_TOP_MARGIN 
SMBMSG$K_UIC 
SMBMSG$K_USER_NAME 

SMBMSG$K_STOP_TASK SMBMSG$K_STOP_CONDITION 

SMBMSG$K_PAUSE_TASK None 

SMBMSG$K_RESUME_TASK SMBMSG$K_ALIGNMENT_PAGES 
SMBMSG$K_RELATIVE_PAGE 
SMBMSG$K_REQUEST_CONTROL 
SMBMSG$K_SEARCH_STRING 

SMBMSG$K_START_STREAM SMBMSG$K_DEVICE_NAME 
SMBMSG$K_EXECUTOR_QUEUE 
SMBMSG$K_JOB_RESET_MODULES 
SMBMSG$K_LIBRARY_SPECIFICATION 

SMBMSG$K_STOP_STREAM None 

SMBMSG$K_RESET_STREAM None 


The following list enumerates each item code. For each code, the list 
describes the contents of the message item identified by the code and 
whether the code identifies an item sent from the job controller to the 
symbiont or from the symbiont to the job controller. 


Many of the codes described are specifically oriented toward print 
symbionts. The symbiont you implement, which might not print files 

or serve an output device, need not recognize all these codes. In addition, 
it need not respond in the same way as the VMS print symbiont to the 
codes it recognizes. The descriptions in the list describe how the standard 
VMS print symbiont (PRTSMB.EXE) processes these items. 


Because new codes might be added in the future, you should write 
your symbiont so that it ignores codes it does not recognize. 


Codes for Message Items 


SMBMSG$K_ACCOUNT_NAME 


This code identifies a string containing the name of the account to be 
charged for the job, that is, the account of the process that submitted the 
print job. 


SMBMSG$K_AFTER_TIME 
This code identifies a 64-bit, absolute-time value specifying the system 
time after which the job controller can process this job. 
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SMBMSG$K_ALIGNMENT_PAGES 


This code identifies a longword specifying the number of alignment pages 
that the symbiont is to print. 


SMBMSG$K_BOTTOM_MARGIN 
This code identifies a longword containing the number of lines to be left 
blank at the bottom of a page. 


The symbiont inserts a formfeed character into the output stream if it 
determines that all of the following conditions are true: 


¢ The number of lines left at the bottom of the page is equal to the value 
in SMBMSG$K_BOTTOM_MARGIN 


e¢ Sending more data to the printer to be output on this page would 
cause characters to be printed within this bottom margin of the page 


¢ The /FEED qualifier was specified with the PRINT command that 
caused the symbiont to perform this task 


(Linefeed, formfeed, carriage-return, and vertical-tab characters in the 
output stream are collectively known as embedded carriage control.) 


SMBMSG$K_CHARACTERISTICS 

This code identifies a 16-byte structure specifying characteristics of the job. 
A detailed description of the format of this structure is contained in the 
description of the QUI$¢_CHARACTERISTICS code in the SYS$GETQUI 
system service in the VMS System Services Reference Manual. 


SMBMSG$K_DEVICE_NAME 

This code identifies a string that is the name of the device to which the 
symbiont is to send data. The symbiont interprets this information. The 
name need not be the name of a physical device, and the symbiont can 
interpret this string as something other than the name of a device. 


SMBMSG$K_ENTRY_NUMBER 
This code identifies a longword containing the number that the job 
controller assigned to the job. 


SMBMSG$K_EXECUTOR_QUEUE 
This code identifies a string that is the name of the queue on which the 
symbiont stream is to be started. 


SMBMSG$K_FILE_COPIES 
This code identifies a longword containing the number of copies of the file 
that were requested. 


SMBMSG$K_FILE_COUNT 


This code identifies a longword that specifies, out of the number of copies 
requested for this job (SMBMSG$K_FILE_COPIES), the number of the 
copy of the file currently printing. 


SMBMSG$K_FILE_IDENTIFICATION 


This code identifies a 28-byte structure identifying the file to be processed. 
This structure consists of the following three file-identification fields in the 
RMS NAM block: 


1 The 16-byte NAM$T_DVI field 
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2 The 6-byte NAM$W_FID field 
3 The 6-byte NAM$W_DID field 


These fields occur consecutively in the NAM block in the order listed. 


SMBMSG$K_FILE_SETUP_MODULES 


This code identifies a string specifying the names (separated by commas) 
of one or more text modules that the symbiont should copy from the library 
into the output stream before processing the file. 


SMBMSG$K_FILE_SPECIFICATION 


This code identifies a string specifying the name of the file that the 
symbiont is to process. This file name is formatted as a standard RMS file 
specification. 


SMBMSG$K_FIRST_PAGE 

This code identifies a longword containing the number of the page at which 
the symbiont should begin printing. The job controller sends this item to 
the symbiont. When not specified, the symbiont begins processing at 

page 1. 


SMBMSG$K_FORM_LENGTH 
This code identifies a longword value specifying the length (in lines) of the 
physical form (the paper). 


SMBMSG$K_FORM_NAME 
This code identifies a string specifying the name of the form. 


SMBMSG$K_FORM_SETUP_MODULES 

This code identifies a string consisting of the names (separated by commas) 
of one or more modules that the symbiont should copy from the device- 
control library before processing the file. 


SMBMSG$K_FORM_WIDTH 
This code identifies a longword specifying the width (in characters) of the 
print area on the physical form (the paper). 


SMBMSG$K_JOB_COPIES 
This code identifies a longword specifying the requested number of copies 
of the job. 


SMBMSG$K_JOB_COUNT 

This code identifies a longword specifying, out of the number of copies 
requested (SMBMSG$K_JOB_COPIES), the number of the copy of the job 
currently printing. 


SMBMSG$K_JOB_NAME 
This code identifies a string specifying the name of the job. 


SMBMSG$K_JOB_RESET_MODULES 

This code identifies a string specifying a list of one or more modules names 
(separated by commas) that the symbiont should copy from the device- 
control library after processing the task. These modules can be used to 
reset programmable devices to a known state. 
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SMBMSG$K_LAST_PAGE 

This code identifies a longword specifying the number of the last page that 
the symbiont is to print. When not specified, the symbiont attempts to 
print all the pages in the file. 


SMBMSG$K_LEFT_MARGIN 
This code identifies a longword specifying the number of spaces to be 
inserted at the beginning of each line. 


SMBMSG$K_LIBRARY_SPECIFICATION 
This code identifies a string specifying the name of the device-control 
library. 


SMBMSG$K_MESSAGE_VECTOR 
This code identifies a vector of longword condition codes, each of which 
contains information about the job to be printed. 


When LOGINOUT cannot open a log file for a batch job, a code in the 
message vector specifies the reason for the failure. The job controller does 
not send the SMBMSG$K_FILE_IDENTIFICATION item if it has detected 
such a failure but instead sends the message vector, which the symbiont 
prints, along with a message stating that there is no file to print. 


SMBMSG$K_NOTE 
This code identifies a user-supplied string that the symbiont is to print on 
the job-flag page and on the file-flag page. 


SMBMSG$K_PAGE_SETUP_MODULES 

This code identifies a string consisting of the names (separated by commas) 
of one or more modules that the symbiont should copy from the device- 
control library before printing each page. 


SMBMSG$K_PARAMETER_1 through SMBMSG$K_PARAMETER_8 


Each of these eight codes identifies a user-supplied string. Both the 
semantics and syntax of each string are determined by the user-defined 
symbiont. The VMS-supplied symbiont makes no use of these eight items. 


SMBMSG$K_PRINT_CONTROL 

This code identifies a longword bit vector, each bit of which supplies 
information that the symbiont is to use in controlling the printing of the 
file. 
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The $SMBDEF macro defines the following symbols for each bit in the bit 
vector: 
Symbol Description 


SMBMSG$V_DOUBLE_SPACE _ The symbiont uses a double-spaced format; it 
skips a line after each line it prints. 


SMBMSG$V_NORECORD_ The symbiont performs single record output, 

BLOCKING issuing a single output record for each input 
record. 

SMBMSG$V_PAGE_HEADER The symbiont prints a page header at the top of 
each page. 

SMBMSG$V_PAGINATE The symbiont inserts a formfeed character when it 


detects an attempt to print in the bottom margin of 
the current form. 


SMBMSG$V_PASSALL The symbiont prints the file without formatting 
and bypasses all formatting normally performed. 
Furthermore, the symbiont outputs the file without 
formatting, by causing the output QIO to suppress 
formatting by the driver. 


SMBMSG$V_RECORD_ The symbiont performs record blocking, buffering 

BLOCKING output to the device. 

SMBMSG$V_SEQUENCED This bit is reserved by Digital. 

SMBMSG$V_SHEET_FEED The symbiont pauses the queue after each page it 
prints. 

SMBMSG$V_TRUNCATE The symbiont truncates input lines that exceed the 
right margin of the current form. 

SMBMSG$V_WRAP The symbiont wraps input lines that exceed the 
right margin, printing the additional characters on a 
new line. 


SMBMSG$K_PRIORITY 
This code identifies a longword specifying the priority this job has in the 
queue in which it is entered. 


SMBMSG$K_QUEUE 

This code identifies a string specifying the name of the queue in which this 
job is entered. When generic queues are used, this item specifies the name 
of the generic queue, and the SMBMSG$K_EXECUTOR item specifies the 
name of the device queue or the server queue. 


SMBMSG$K_RELATIVE_PAGE 

This code identifies a signed, longword value specifying the number of 
pages that the symbiont is to move forward (positive value) or backward 
(negative value) from the current position in the file. 


SMBMSG$K_REQUEST_CONTROL 

This code identifies a longword bit vector each bit of which specifies 
information that the symbiont is to use in processing the request that 
the job controller is making. The $SMBDEF macro defines the following 
symbols for each bit: 
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Symbol 
SMBMSG$V_ALIGNMENT_MASK 


SMBMSG$V_PAUSE_COMPLETE 
SMBMSG$V_RESTARTING 


SMBMSG$V_TOP_OF_FILE 


SMBMSG$K_RIGHT_MARGIN 


SMB$READ_MESSAGE_ITEM 


Description 


The symbiont is to replace all alphabetic 
characters with the letter X, and all numeric 
characters with the number 9. Other characters 
(punctuation, carriage control, and so on) are 
left unchanged. This bit is ordinarily specified in 
connection with the SMBMSG$K_ALIGNMENT_. 
PAGES item. 


The symbiont is to pause when it completes the 
current request. 


Indicates that this job was previously interrupted 
and requeued, and is now restarting. 


The symbiont is to rewind the input file before it 
resumes printing. 


This code identifies a longword specifying the number of character 
positions to be left empty at the end of each line. When the right margin 
is exceeded, the symbiont truncates the line, wraps the line, or continues 
processing, depending on the settings of the WRAP and TRUNCATE bits 
in the SMBMSG$K_PRINT_CONTROL item. 


SMBMSG$K_SEARCH_STRING 


This code identifies a string containing the value specified in the START 
/QUEUE/SEARCH command. This string identifies the page at which to 


restart the current printing task 


on a paused queue. 


SMBMSG$K_SEPARATION_CONTROL 
This code identifies a longword bit vector, each bit of which specifies an 


operation that the symbiont is to perform between jobs or between files 
within a job. The $SMBDEF macro defines the following symbols for each 


bit: 


Symbol 


SMBMSG$V_FILE_BURST 
SMBMSG$V_FILE_FLAG 
SMBMSG$V_FILE_TRAILER 
SMBMSG$V_FILE_TRAILER_ABORT 


SMBMSG$V_FIRST_FILE_OF_JOB 


SMBMSG$V_JOB_FLAG 
SMBMSG$V_JOB_BURST 
SMBMSG$V_JOB_RESET 


Description 


_ The symbiont is to print a file-burst page. 
The symbiont is to print a file-flag page. 
The symbiont is to print a file-trailer page. 


The symbiont is to print a file-trailer page 
when a task completes abnormally. 


The current file is the first file of the job. 
When specified with SMBMSG$V_LAST_ 
FILE_OF_JOB, the current job contains a 
single file. 


The symbiont is to print a job-flag page. 
The symbiont is to print a job-burst page. 


The symbiont is to execute a job-reset 
sequence when the task completes. 
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Symbol Description 

SMBMSG$V_JOB_RESET_ABORT The symbiont is to execute a job-reset 
sequence when a task completes 
abnormally. 

SMBMSG$V_JOB_TRAILER The symbiont is to print a job-trailer page. 


SMBMSG$V_JOB_TRAILER_ABORT The symbiont is to print a job-trailer page 
when a task completes abnormally. 


SMBMSG$V_LAST_FILE_OF_JOB The current file is the last file of the job. 
When specified with SMBMSG$V_FIRST_ 
FILE _OF_JOB, the current job contains a 
single job. 


SMBMSG$K_STOP_CONDITION 
This code identifies a longword containing a condition specifying the 
reason the job controller issued a STOP_TASK request. 


SMBMSG$K_TIME_QUEUED 
This code identifies a quadword specifying the time the file was entered 
into the queue. The time is expressed as 64-bit, absolute time. 


SMBMSG$K_TOP_MARGIN 


This code identifies a longword specifying the number of lines that the 
symbiont is to leave blank at the top of each page. PRTSMB inserts 
linefeeds into the output stream after every formfeed until the margin is 
cleared. 


SMBMSG$K_UIC 
This code identifies a longword specifying the User Identification Code 
(UIC) of the user who submitted the job. 


SMBMSG$K_USER_NAME 


This code identifies a string specifying the name of the user who submitted 
the job. 





CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL Routine completed successfully. 
SMB$_NOMOREITEMS End of item list reached. 


This routine also returns any condition code returned by the Run-Time 
Library string-handling (STR$) routines. 
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SMB$SEND_TO JOBCTL Send Message to Job 
Controller 
The SMB$SEND_TO_JOBCTL routine is used by your symbiont to send 


messages to the job controller. Three types of message can be sent: request- 
completion messages, task-completion messages, and task-status messages. 





FORMAT SMB$SEND_TO JOBCTL stream [,requesi] 
[accounting] [, checkpoint] 
[,device_status] [,error] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS _ stream 
VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Stream number specifying the stream to which the message refers. The 
stream argument is the address of a longword containing the number of 
the stream to which the message refers. 


request 

VMS usage: identifier 

type: longword (unsigned) 
access: read only 


mechanism: by reference 

Request code identifying the request being completed. The request 
argument is the address of a longword containing the code that identifies 
the request that has been completed. 


The code usually corresponds to the code the job controller passed to the 
symbiont by means of a call to SMB$READ_MESSAGE. But the symbiont 
can also initiate task-completion and task-status messages that are not in 
response to a request. (See the DESCRIPTION section.) 


SMB-31 


Symbiont/Job Controller Interface (SMB) Routines 
SMB$SEND_TO_JOBCTL 


SMB-32 


Note: 


accounting 


VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Accounting information about a task. The accounting argument is the 
address of a descriptor pointing to the accounting information about a 
task. Note that this structure is passed by descriptor and not by reference. 


The job controller accumulates task statistics into a job-accounting record, 
which it writes to the accounting file when the job is completed. 


The following diagram depicts the contents of the 16-byte structure: 
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checkpoint 


VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Checkpoint data about the currently executing task. The checkpoint 
argument is the address of the descriptor that points to checkpointing 
information that relates to the status of a task. When the symbiont sends 
this information to the job controller, the job controller saves it in the 
queue database. When a restart-from-checkpoint request is executed for 
the queue, the job controller retrieves the checkpointing information from 
the queue database and sends it to the symbiont in the SMBMSG$K_ 
CHECKPOINT_DATA item that accompanies a SMBMSG$K_START_ 
TASK request. 


Print symbionts can use the checkpointing information to reposition the 
input file to the point corresponding to the page being output when the last 
checkpoint was taken. Other symbionts might use checkpoint information 
to specify restart information for partially completed tasks. 


Because each checkpoint causes information to be written 

into the job controller’s queue database, taking a checkpoint 
incurs significant overhead. Use caution in regard to the size 
and frequency of checkpoints. When determining how often to 
checkpoint, weigh processor and file-system overhead against the 
convenience of restarting. 
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device_status 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Status of the device served by the symbiont. The device_status argument 
is the address of a longword passed to the job controller, which contains 
the status of the device to which the symbiont is connected. 


This longword contains a longword bit vector, each bit of which specifies 
device-status information. The $SMBDEF macro defines these device- 
status bits. The following table describes each bit: 


Device Status Bit Description 

SMBMSG$V_LOWERCASE The device to which the symbiont is connected 
supports lowercase characters. 

SMBMSG$V_PAUSE_TASK The symbiont sends this message to inform the job 
controller that the symbiont has paused on its own 
initiative. 

SMBMSG$V_REMOTE The device is connected to the symbiont by means 
of a modem. 

SMBMSG$V_SERVER The symbiont is not connected to a device. 

SMBMSG$V_STALLED Symbiont processing is temporarily stalled. 

SMBMSG$V_STOP_STREAM The symbiont requests that the job controller stop 
the queue. 

SMBMSG$V_TERMINAL The symbiont is connected to a terminal. 

SMBMSG$V_UNAVAILABLE The device to which the symbiont is connected is 
not available. 

error 

VMS usage: vector_longword_unsigned 

type: longword (unsigned) 

access: read only 


mechanism: by reference 

Condition codes returned by the requested task. The error argument is 
the address of a vector of longword condition codes. The first longword 
contains the number of longwords following it. 


If the low bit of the first condition code is clear, the job controller aborts 
further processing of the job. Output of any remaining files, copies of files, 
or copies of the job is canceled. In addition, the job controller saves up to 
three condition values in the queue database. The first condition value 

is included in the job-accounting record that is written to the system’s 
accounting file (SYS$MANAGER:ACCOUNTNG.DAT). 
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DESCRIPTION _ The symbiont uses the SMB$SEND_TO_JOBCTL routine to send 
messages to the job controller. 


Most messages the symbiont sends to the job controller are responses 

to requests made by the job controller. These responses inform the job 
controller that the request has been completed, either successfully or with 
an error. When the symbiont sends the message, it usually indicates that 
the request has been completed. 


In such messages, the request argument corresponds to the function code 
of the request that has been completed. Thus, if the job controller sends a 
request using the SMBMSG$K_START_TASK code, the symbiont responds 
by sending a SMB$SEND_TO_JOBCTL message using SMBMSG$K_ 
START_TASK as the request argument. 


The responses to some requests use additional argumen‘s to send more 
information in addition to the request code. The following table shows 
which additional arguments are allowed in response to each different 
request: 


Request Arguments 


SMBMSG$K_START_STREAM request 
device_status 
error 

SMBMSG$K_STOP_STREAM request 

SMBMSG$K_RESET_STREAM request 


SMBMSG$K_START_TASK request 
SMBMSG$K_PAUSE_TASK request 
SMBMSG$K_RESUME_TASK request 
SMBMSG$K_STOP_TASK request 


error’ 


'This is usually the value specified in the SMBMSG$K_STOP_CONDITION item that was sent 
by the job controller with the SMBMSG$K_STOP_TASK request. 


In addition to responding to requests from the job controller, the 
symbiont can send other messages to the job controller. If the symbiont 
sends a message that is not a response to a request, it uses either 

the SMBMSG$K_TASK_COMPLETE or SMBMSG$K_TASK_STATUS 
code. Following are the additional arguments that you can use with the 
messages identified by these codes: 
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Code Arguments 

SMBMSG$K_TASK_COMPLETE request 
accounting 
error 

SMBMSG$K_TASK_STATUS request 
checkpoint 


device_status 


The symbiont uses the SMBMSG$K_TASK_STATUS message to update 
the job controller on the status of a task during the processing of that 
task. The checkpoint information passed to the job controller with this 
message permits the job controller to restart an interrupted task from an 
appropriate point. The device-status information permits the symbiont to 
report changes in device’s status (device stalled, for example). 


The symbiont can use the SMBMSG$K_TASK_STATUS message to 
request that the job controller send a stop-stream request. It does this 
by setting the stop-stream bit in the device-status argument. 


The symbiont can also use the SMBMSG$K_TASK_STATUS message to 
notify the job controller that the symbiont has paused in processing a task. 
It does so by setting the pause-task bit in the device-status argument. 


The symbiont uses the SMBMSG$K_TASK_COMPLETE message to 
signal the completion of a task. Note that, when the symbiont receives a 
START_TASK request, it responds by sending a SMB$SEND_TO_JOBCTL 
message with SMBSMG$K_START_TASK as the request argument. This 
response means that the symbiont has started the task; it does not mean 
the task has been completed. When the symbiont has completed a task, 

it sends a SMB$SEND_TO_JOBCTL message with SMBMSG$K_TASK_ 
COMPLETE as the request argument. 


Optionally, the symbiont can specify accounting information when sending 
a task-completion message. The accounting statistics accumulate to give a 
total for the job when the job is completed. 


Also, if the symbiont is aborting the task because of a symbiont-detected 
error, you can specify up to three condition values in the error argument. 
Aborting a task causes the remainder of the job to be aborted. 





CONDITION 
RETURNED 


SS$_NORMAL Routine completed successfully. 


This routine also returns any condition value returned by the $QIO system 
service and the LIB$GET_VM routine. 
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1 3 Sort/Merge (SOR) Routines 


The SOR routines allow you to integrate a sort or merge operation into a 
program application. Using these callable routines, you can process some 
records, sort or merge them, and then process them again. 





13.1 Introduction to SOR Routines 


Note: 


The following SOR routines are available for use in a sort or merge 
operation: 


SOR$BEGIN_MERGE _ Sets up key arguments and performs the merge. This is the 
only routine unique to MERGE. 


SORS$BEGIN_SORT Initializes sort operation by passing key information and sort 
options. This is the only routine unique to SORT. 

SOR$DTYPE Defines a key data-type that is not normally supported by 
SORT/MERGE. 

SORSEND_SORT Performs cleanup functions, such as closing files and 
releasing memory. 

SOR$PASS_FILES Passes names of input and output files to SORT or MERGE; 


must be repeated for each input file. 


SOR$RELEASE_REC Passes one input record to SORT or MERGE; must be 
called once for each record. 


SOR$RETURN_REC Returns one sorted or merged record to a program; must be 
called once for each record. 


SORSSORT_MERGE Sorts the records. 


SOR$SPEC_FILE Passes a specification file or specification text. A call to this 
routine must precede all other cails to the SOR routines. 

SORS$STAT Returns a statistic about the sort or merge operation. 

You can still call SOR$DO_MERGE (from VMS Version 3.0) as 


the equivalent of SOR$END_SORT; you can still call SOR$INIT_ 
MERGE and SORS$INIT_SORT (from VMS Version 3.0) as the 
equivalent of SOR$BEGIN_SORT and SOR$BEGIN_MERGE. 
However, for any new programs that you are creating, you 

are advised to use SORSEND_SORT, SOR$BEGIN_SORT, and 
SOR$BEGIN_MERGE. 


You can call these SOR routines from any language that supports the 
VAX Procedure Calling and Condition Handling Standard. Note that the 
application program should declare referenced constants and return status 
symbols as external symbols; these symbols will be resolved upon linking 
with utility shareable image. 


After being called, each of these routines performs its function and 
returns control to a program. It also returns a 32-bit condition code 
value indicating success or error, which a program can test to determine 
success or failure conditions. 
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13.1.1 Arguments to SOR Routines 


For a sort operation, the arguments to the SOR routines provide SORT 
with file specifications, key information, and instructions about the sorting 
process. For a merge operation, the arguments to the SOR routines 
provide MERGE with the number of input files, input and output file 
specifications, record information, key information, and input routine 
information. 


There are both mandatory and optional arguments. The mandatory 
arguments appear first in the argument list. You must specify all 
arguments in the order in which they are positioned in the argument 
list, separating each with a comma. Pass a zero by value to specify any 
optional arguments that you are omitting from within the list. You can 
end the argument list any time after specifying all the mandatory and 
desired optional arguments. 


13.1.2 Interfaces to SOR Routines 
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You can submit data to the SOR routines as complete files or as single 
records. When your program submits one or more files to SORT or 
MERGE, which then creates one sorted or merged output file, you are 
using the file interface. When your program submits records one at a time 
and then receives the ordered records one at a time, you are using the 
record interface. 


You can combine the file interface with the record interface by submitting 
files on input and receiving the ordered records on output or by releasing 
records on input and writing the ordered records to a file on output. 
Combining the two interfaces provides greater flexibility. If you use the 
record interface on input, you can process the records before they are 
sorted; if you use the record interface on output, you can process the 
records after they are sorted. 


The SOR routines used and the order in which they are called depend 
on the type of interface used in a sorting or merging operation. The 
following sections detail the calling sequence for each of the interfaces. 
Note, however, that if you use the SOR$STAT routine, it must be called 
before any other SOR routine. 


Sort Operation Using File Interface 


For a sort operation using the file interface, pass the input and output 
file specifications to SORT by calling SOR$PASS_FILES. You must call 
SOR$PASS_FILES for each input file specification. Pass the output file 
specification in the first call. If no input files are specified before the call 
to SOR$BEGIN_SORT, the record interface is used for input; if no output 
file is specified, the record interface is used for output. 


Next, call SOR$BEGIN_SORT to pass instructions about keys and sort 
options. At this point, you must indicate whether you want to use 

your own key comparison routine. SORT automatically generates a key 
comparison routine that is efficient for key data types; however, you might 
want to provide your own comparison routine to handle special sorting 
requirements. (For example, you might want names beginning with “Mc” 
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and “Mac” to be placed together.) If you use your own key comparison 
routine, you must pass its address with the user_compare argument. 


Call SOR$SORT_MERGE to execute the sort and direct the sorted records 
to the output file. Finally, call SOR$END_SORT to end the sort and 
release resources. The SOR$END_SORT routine can be called at any time 
to abort a sort or to merge and release all resources allocated to the sort or 
merge process. 


13.1.2.2 Sort Operation Using Record Interface 
For a sort operation using the record interface, first call SOR$6BEGIN_ 
SORT. As in the file interface, this routine sets up work areas and passes 
arguments that define keys and sort options. Note that, if you use the 
record interface, you must use a record-sorting process (not a tag, address, 
or index process). 


Next, call SOR$RELEASE_REC to release a record to SORT. Call 
SOR$RELEASE_REC once for each record to be released. After all records 
have been passed to SORT, call SOR$SORT_MERGE to perform the 
sorting. 


After the sort has been performed, call SOR$SRETURN_REC to return a 
record from the sort operation. Call this routine once for each record to be 
returned. Finally, call the last routine, SORS$END_SORT, to complete the 
sort operation and release resources. 


13.1.2.3 Merge Operation Using File Interface 
For a merge operation using the file interface, pass the input and output 
file specifications to MERGE by calling SOR$PASS_FILES. You can merge 
up to 10 input files by calling SOR$PASS_FILES once for each file. Pass 
the file specification for the merged output file in the first call. If no input 
files are specified before the call to SOR$BEGIN_MERGE, the record 
interface is used for input; if no output file is specified, the record interface 
is used for output. 


Next, to execute the merge, call SOR$SBEGIN_MERGE to pass key 
information and merge options. At this point, you must indicate whether 
you want to use your own key comparison routine tailored to your data. 
Finally, call SORSEND_SORT to release resources. 


13.1.2.4 Merge Operation Using Record Interface 
For a merge operation using the record interface, first call SOR$BEGIN_ 
MERGE. As in the file interface, this routine passes arguments that define 
keys and merge options. It also issues the first call to the input routine, 
which you must create, to begin releasing records to the merge. 


Next, call SOR$RETURN_REC to return the merged records to your 
program. You must call this routine once for each record to be returned. 
SOR$RETURN_REC continues to call the input routine. MERGE, unlike 
SORT, does not need to hold all the records before it can begin returning 
them in the desired order. Releasing, Merging, and Returning of records 
all take place in this phase of the merge. 


Finally, after all the records have been returned, call the last routine, 
SOR$END_SORT, to clean up and release resources. 
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13.1.3 Reentrancy 


13.2 


The SOR routines are reentrant; that is, a number of sort or merge 
operations can be active at the same time. Thus, a program does not 
need to finish one sort or merge operation before beginning another. For 
example, reentrancy lets you perform multiple sorts on a file such as a 
mailing list and to create several output files, one with the records sorted 
by name, another sorted by state, another sorted by zip code, and so on. 


The context argument, which can optionally be passed with any of the 
SOR routines, distinguishes among multiple sort or merge operations. 
When using multiple sort or merge operations, the context argument 

is required. On the first call, the context longword must be zero. It is 
then set (by SORT/MERGE) to a value identifying the sort or merge 
operation. Additional calls to the same sort or merge operation must 
pass the same context longword. The SORS$END_SORT routine clears the 
context longword. 


Examples of Using SOR Routines 


Example 13-1 is a VAX FORTRAN program demonstrating a merge 
operation using a record interface. 


Example 13-1 Using SOR Routines to Perform a Merge Using Record Interface in a VAX 


FORTRAN Program 


FORTRAN Program 


for the merge record interface. 


THE INPUT FILES ARE LISTED BELOW. 


INFILE1.DAT 


INFILE2.DAT 


Nr 


INFILE3.DAT 


qgqggagadqnnaagngaagnganaagnaanagaaagnaadaana 
NO 7. e @ «@ 
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This program demonstrates the FORTRAN calling sequences 


BEEBBEBRBB REST (OF DATA. IN: RECORD. 64.4 9 0 ais.¢.0 0 Se alesse 0s 8 Seals ae 
QDUUUUDUUUU REST OF DATA: IN RECORD. 6o5se0 eee@ eeu £4 eee o HORS S oars 


AAAAAAAAAA REST OF DATA IN RECORD... cccccecccsccescosccrsesssace 
TITTELUPE. -Reoo OF DATA. EN “RECORD siete es ane ee ole Gide Se wie eG bse ee ee Bree 


1: PETTELTLIe Reot OF DATA IN RECORD 604 44:06 wa /eis ew eee tas ae ew Wade ele 
2 BBBBBBBESE:.-RES., OF DATA. IN RECORD: os 4. 4% Swe ww dara <4 oducts ees eaee 


OF 
OF 


OF 
OF 


OF 
OF 


RECORD 
RECORD 


RECORD 
RECORD 


RECORD 
RECORD 
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Example 13—1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in a VAX 


FORTRAN Program 





QAaagaAgagagaanNgagaaganagaANn 


aqaaa 


aqagaaagagaNn 


NNN FF 


FOROUT.DAT 
AAAAAAAAAA REST OF DATA IN RECORD... . 2c eee ee ee eee eee eee eee eee nee END OF RECORD 
BBBBBBBBBB REST OF DATA IN RECORD... ...... ccc cece cc ener eee eee eens END OF RECORD 
TTTTTTTTITT REST OF DATA IN RECORD... ... ee eee eee ere eee ee wee eee e eee END OF RECORD 
BBBBBBBBBB REST OF DATA IN RECORD... 1... ccc cece cece eee eee ee eee ne END OF RECORD 
TTTTTITTIT REST OF DATA IN RECORD... eee e eee ere cc cre reece ec cence END OF RECORD 
UUUUUUUUUU REST OF DATA IN RECORD... 1... eee cere ccc erence rence eerns END OF RECORD 


IMPLICIT INTEGER (A-Z) 


CHARACTER*80 REC ! A record. 

EXTERNAL READ REC ! Routine to read a record. 
EXTERNAL KOMPAR ! Routine to compare records. 
EXTERNAL SS$_ENDOFFILE ! System end-of-file value 
INTEGER*4 SORSBEGIN MERGE ! SORT/MERGE function names 


INTEGER*4 SORSRETURN_REC 
INTEGER*4 SORSEND_ SORT 


INTEGER*4 ISTAT ! storage for SORT/MERGE function value 
INTEGER*4 LENGTH ! length of the returned record 
INTEGER*2 LRL ! Longest Record Length (LRL) 

LOGICAL*1 ORDER ! #files to merge (merge order) 

DATA ORDER, LRL/3, 80/ ! Order of the merge=3, LRL=80 


First open all the input files. 


OPEN (UNIT=10, FILE=’ INFILE1.DAT’ , TYPE=’ OLD’ , READONLY, 
FORM=’ FORMATTED’ ) 

OPEN (UNIT=11, FILE=’ INFILE2.DAT’ , TYPE=’ OLD’ , READONLY, 
FORM=’ FORMATTED’ ) 

OPEN (UNIT=12, FILE=’ INFILE3.DAT’ , TYPE=’ OLD’ , READONLY, 
FORM=’ FORMATTED’ ) 


Open the output file. 

OPEN (UNIT=8, FILE=’ TEMP.TMP’, TYPE=’ NEW’ ) 

Initialize the merge. Pass the merge order, the largest 
record length, the compare routine address, and the 


input routine address. 


ISTAT = SORSBEGIN_ MERGE (, LRL, , ORDER, 
KOMPAR, , READ_REC) 
IF (.NOT. ISTAT) GOTO 10 ! Check for error. 





{continued on next page) 
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Example 13-1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in a VAX 
FORTRAN Program 


Cees 
Cres Now loop getting merged records. SORSRETURN_REC will 
Cisse call READ REC when it needs input. 
Cc se 
5 ISTAT = SORSRETURN_REC (REC, LENGTH) 
IF (ISTAT .EQ. %LOC(SS$_ENDOFFILE)) GO TO 30 ! Check for end of file. 
IF (.NOT. ISTAT) GO TO 10 ! Check for error. 
WRITE (8,200) REC ! Output the record. 
200 FORMAT (’ ‘’,A) 
GOTO 5 ! And loop back. 
Cie 
Gis Now tell SORT that we are all done. 
epee 
30 ISTAT = SORSEND_SORT() 
IF (.NOT. ISTAT) GOTO 10 ! Check for error. 
CALL EXIT 
C.. 
C.. Here if an error occurred. Write out the error status 
C.. and exit. 
Cnels 
10 WRITE (8,201) ISTAT 
201 FORMAT (’ ?ERROR CODE’, 120) 
CALL EXIT 
END 
FUNCTION READ REC (RECX, FILE, SIZE) 
Cains 
Cas This routine reads a record from one of the input files 
Gs for merging. It will be called by SORS$BEGIN_ MERGE and by 
Cc. SORSRETURN_REC. 
Cc. Parameters: 
Cc. 
Cc. RECX.wep.ds character buffer to hold the record after 
Cc. it is read in. 
Cas 
Cc. FILE.rl.xr indicates which file the record is 
on to be read from. 1 specifies the 
Cavs first file, 2 specifies the second 
Ce etc. 
oe 
Crete LENGTH.wl.r is the actual number of bytes in 
Cree the record. This is set by READ REC. 
Cc ° 
IMPLICIT INTEGER (A-Z) 
PARAMETER MAXFIL=10 ! Max number of files. 
EXTERNAL SS$_ENDOFFILE ! End of file status code. 
EXTERNAL SS$_NORMAL ! Success status code. 


LOGICAL*1 FILTAB (MAXFIL) 
CHARACTER* (80) RECX ! MAX LRL =80 


DATA FILTAB/10,11,12,13,14,15,16,17,18,19/ ! Table of I/O unit numbers. 





(continued on next page) 
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Example 13—1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in a VAX 


FORTRAN Program 





100 


Cie ats 


ws) 


AAAAARAA 


20 


50 


READ REC = %LOC(SS$_ENDOFFILE) ! Give end of file return 

IF (FILE .LT. 1 .OR. FILE .GT. MAXFIL) RETURN ! if illegal call. 
READ (FILTAB(FILE), 100, ERR=75, END=50) RECX ! Read the record. 
FORMAT (A) 

READ _REC = %LOC(SS$_NORMAL) ! Return success code. 

SIZE = LEN (RECX) ! Return size of record. 
RETURN 

Here if end of file. 

READ REC = %LOC(SS$_ENDOFFILE) ! Return "end of file" code. 
RETURN 


Here if error while reading 
READ _REC = 0 

SIZE = 0 

RETURN 

END 


FUNCTION KOMPAR (REC1, REC2) 


This routine compares two records. It returns -1 

if the first record is smaller than the second, 

0 if the records are equal, and 1 if the first record 
is larger than the second. 


PARAMETER KEYSIZ=10 
IMPLICIT INTEGER (A-2Z) 
LOGICAL*1 REC1 (KEYSIZ) , REC2 (KEYSIZ) 


DO 20 I=1,KEYSI2Z 

KOMPAR = REC1(I) - REC2 (TI) 
IF (KOMPAR .NE.._ 0) GOTO 50 
CONTINUE 


RETURN 


KOMPAR = ISIGN (1, KOMPAR) 
RETURN 
END 





Example 138-2 is a VAX FORTRAN program demonstrating a sort 
operation using a file interface on input and a record interface on output. 
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Example 13-2 Using SOR Routines to Sort Using Mixed Interface in a VAX FORTRAN Program 





Program 


PROGRAM CALLSORT 


Cc 
Cc 
Cc This is a sample FORTRAN program that calls the SOR 
Cc routines using the file interface for input and the 
C record interface for output. This program requests 
Cc a record sort of the file ’RO10SQ.DAT’ and writes 
C the records to SYSSOUTPUT. The key is an 80-byte 
C character ascending key starting in position 1 of 
Cc each record. 
Cc 
c A short version of the input and output files follows: 
Cc 
Cc Input file RO10SQ.DAT 
C 1 BBBBBBBBBB REST OF DATA IN RECORD...... cece e nec c cca cccctacccace END OF RECORD 
C 2 UUUUUUUUUU REST OF DATA IN RECORD... ccc ccc ccc cece cece eee et ee eens END OF RECORD 
C 1 AAAAAAAAAA REST OF DATA IN RECORD... ce ccc ce eee eee eter eee tere wees END OF RECORD 
C 2 TTTTTTTTTT REST OF DATA IN RECORD... ccc cc ccc eee ec cent twee etc enee END OF RECORD 
C 1 TITTTTTTTT REST OF DATA IN RECORD... .. ccc ee eee eee eee ew ee eer eens END OF RECORD 
C 2 BBBBBBBBBB REST OF DATA IN RECORD... ..c eee c ete cee een cee r ec eeee END OF RECORD 
C 1 QQ0Q0Q0Q000000 REST OF DATA IN RECORD....... ccc cence nce c nc nnecrnncceen END OF RECORD 
C 2 AAAAAAAAAA REST OF DATA IN RECORD... . cc ccc ee ccc ewe eee ene c eee ens END OF RECORD 
C 1 UUUUUUUUUU REST OF DATA IN RECORD... cc cece cc eee eee eter ete eee aee END OF RECORD 
C 2 QO0O0000000 REST OF DATA IN RECORD... ccc eee cc nec cee ee cee etc e eae END OF RECORD 
Cc 
Cc Output file SYSSOUTPUT 
Cc 
C 1 AAAAAAAAAA REST OF DATA IN RECORD... cc cee cece eee eee etree ee ee eeee END OF RECORD 
C 1 BBBBBBBBBB REST OF DATA IN RECORD... .. ccc ec eee ee eee te eet teens END OF RECORD 
C*-t-DOGOO00000 : REST “OF ‘DATA. “IN RECORD sci So oe: Se ere:d iwi ncecere acai we Gielen Ss END OF RECORD 
CL TILITETITCTT REST: OF “DATA: IN RECORD vos ed.ari eee 8 eee ilar ele bee one iw ees 6 8 END OF RECORD 
C 1 UUUUUUUUUU REST OF DATA IN RECORD........e ee ees ee eee Oe END OF RECORD 
C 2 AAAAAAAAAA REST OF DATA IN RECORD..... cece cece cece ccces Lister Geto dete ts END OF RECORD 
¢ 2 BBBBEBEEBB REST OF DATA IN RECORD ee-< 6 elewies a Sewie e's bee eo Oe we ire See END OF RECORD 
€ 2 QQOOOOCCO00 ‘REST OF DATA “IN RECORD 9:5-< 6.6% Ww. eo iew § MW wlecee Be Bee wee END OF RECORD 
C2: -TTITITITEE: REST OF DATA: IN RECORD 66a asec id 0 seis we. asec ware wow 0 Sree, weed ek END OF RECORD 
C:.2 USUUUUUUUU: REST OF ‘DATA. IN: RECORD i046 54 4 bese S ss Oiiwk é HES Se ed owe ee END OF RECORD 
Cc 
es a a i a a ere ee ss ce es ee ns ee a ae ss ee ee ee ee oe se ee ee ee ee 
C 
Cc Define external functions and data. 
C 

CHARACTER*80 RECBUF 

CHARACTER*10 INPUTNAME !Input file name 

INTEGER*2 KEYBUF (5) 'Key definition buffer 

INTEGER*4 SORSPASS FILES !SORT function names 


INTEGER*4 SOR$BEGIN_SORT 

INTEGER*4 SORSSORT_MERGE 

INTEGER*4 SORSRETURN_REC 

INTEGER* 4 SORSEND_SORT 

INTEGER*4 ISTATUS 'Storage for SORT function value 
EXTERNAL SS$_ENDOFFILE 

EXTERNAL DSCSK_DTYPE_ T 

EXTERNAL SORSGK_RECORD 

INTEGER*4 SRITYPE 





(continued on next page) 
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Example 13-2 (Cont.) Using SOR Routines to Sort Using Mixed Interface in a VAX FORTRAN 





Program 
Cc 
Cc Initialize data -- first the file names, then the key buffer for 
c one 80-byte character key starting in position 1, 3 work files, 
Cc and a record sort process. 
Cc 
DATA INPUTNAME/’R010SQ.DAT’ / 
KEYBUF (1) = 1 
KEYBUF (2) = $LOC (DSCS$K_DTYPE T) 
KEYBUF (3). = 0 
KEYBUF (4) = 0 
KEYBUF (5) = 80 
SRTTYPE = %LOC (SORS$GK_RECORD) 
Cc 
Cc Call the SORT -- each call is a function. 
Cc 
Cc 
C Pass SORT the file names. 
Gc 
ISTATUS = SORSPASS FILES (INPUTNAME) 
IF (.NOT. ISTATUS) GOTO 10 
Cc 
Cc Initialize the work areas and keys. 
Cc 
ISTATUS = SORSBEGIN SORT (KEYBUF,,,,,,SRTTYPE, SREF (3) ) 
IF (.NOT. ISTATUS) GOTO 10 
Cc 
Cc Sort the records. 
Cc 
ISTATUS = SORSSORT_MERGE( ) 
IF (.NOT. ISTATUS) GOTO 10 
Cc 
Cc Now retrieve the individual records and display them. 
Cc 
5 ISTATUS = SORSRETURN_REC (RECBUF) 
IF (.NOT. ISTATUS) GOTO 6 
ISTATUS = LIBS$PUT_OUTPUT (RECBUF) 
GOTO 5 
6 IF (ISTATUS .EQ. %LOC (SS$_ENDOFFILE) ) GOTO 7 
GOTO 10 
Cc 
Cc Clean up the work areas and files. 
Cc 
7 ISTATUS = SORSEND_ SORT () 
IF (.NOT. ISTATUS) GOTO 10 
STOP -’SORT SUCCESSFUL’ 
10 STOP 'SORT UNSUCCESSFUL’ 


END 





Example 13-3 is a VAX Pascal program demonstrating a merge operation 
using a file interface. 
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Example 13-3 Using SOR Routines to Merge Three Input Files in a VAX Pascal Program 





Program 


(* This program merges three input files, 
IN_FILE2.DAT IN _FILE3.DAT), and creates one merged output file. 


(IN_FILE.DAT, 


oo) 


program mergerecs( output, in_filel, in_file2, in_file3, out_file ); 


CONST 


SS$_NORMAL = 1; 


SS$_ENDOFFILE = %X870; 


SOR$GK_RECORD = 1; 
SOR$M_STABLE = 1 
SOR$M_SEQ_ CHECK 
SOR$M_SIGNAL = 8 


DSCS$K_DTYPE_T = 14; 


4; 


[WORD] 0..65535; 


TYPE 
SUBYTE = [BYTE] 0..255; 
SUWORD = 

const 
num_of_keys = 1; 
merge order = 3; 
irl = 131; 
ascending = 0; 
descending = 1; 


type 

key buffer _block= 
packed record 
key type: 
key order: 
key offset: 
key length: 
end; 


key buffer _type= 
packed record 
key count: 
blocks: 
end; 


record buffer = 


record _buffer descr 


packed record 


length: S$uword; 
Suword; 
“record buffer; 


dummy : 
addr: 
end; 


Suword; 
Suword; 
Suword; 
Suword; 


Suword; 
packed array[1..num_of keys] of 


packed array[{1l..lrl] of char; 


key buffer_block; 
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Example 13-3 (Cont.) Using SOR Routines to Merge Three Input Files in a VAX Pascal Program 





var 
in filel, 
in ftile2, 
in tiles, 
out_file: text; 
key buffer: key _buffer_type; 
rec_buffer: record buffer; 
rec_length: Suword; 
status: integer; 
i: integer; 


function sor$begin_merge ( 


var buffer: key buffer type; 
lrl: Suword; 

mrg_ options: integer; 

merge order: Subyte; 

Simmed cmp_rtn: integer := 0; 
simmed eql_rtn: integer := 0; 


S$immed [unbound] function 
read_record ( 
var rec: - record buffer descr; 
var filenumber: integer; 
var recordsize: Suword): integer 
): integer; extern; 


function sor$return_rec ( 
Sstdescr rec: record buffer; 
var rec_size: Suword 
): integer; extern; 


function sor$Send_sort: integer; extern; 
procedure sysSexit( Simmed status : integer ); extern; 


function read_record ( 
var rec: record buffer descr; 
var filenumber: integer; 
var recordsize: Suword 
): integer; 


procedure readone( var filename: text ); 
begin 
recordsize := 0; 
if eof (filename) 
then 
read_record := ss$ endoffile 
else 
begin 
while not eoln(filename) and (recordsize < rec.length) do 
begin 
recordsize := recordsize + 1; 
read (filename, rec.addr% [recordsize]); 
end; 
readin (filename) ; 
end; 
end; 





(continued on next page) 
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Example 13-3 (Cont.) Using SOR Routines to Merge Three Input Files in a VAX Pascal Program 





begin 
read_record := ss$_normal; 
case filenumber of 
1: readone(in_filel); 
2: readone(in_filed2) ; 
3: readone(in_file3); 
otherwise 
read_record := ss$_endoffile; 
end; 
end; 


procedure initfiles; 

begin 

open( in_filel, ‘infilel.dat’, old ); 
open( in file2, ’infile2.dat’, old ); 
open( in file3, ‘infile3.dat’, old ); 
open( out_file, ‘temp.tmp’ ); 

reset ( in_filel ); 

reset ( in_file2 ); 

reset ( in file3 ); 

rewrite( out_file ); 

end; 


procedure error( status : integer ); 

begin 

writeln( ’merge unsuccessful. status=%x’, status:8 hex ); 
sysS$exit (status); 

end; 


begin 


with key buffer do 

begin 

key count := 1; 

with blocks[1] do 
begin 
key type := dsc$k_dtype t; 
key order := ascending; 
key offset := 0; 
key length := 5; 
end; 

end; 


initfiles; 


status := sor$begin_merge( key buffer, lrl, 
sor$m_seq_ check + sor$m_signal, 
merge order, 0, 0, read_record ); 


repeat 
begin 
rec_ length := 0; 
status := sorSreturn_rec( rec_buffer, rec_length ); 
if odd(status) 
then 
begin 
for i := 1 to rec_length do write(out_file, rec_buffer[i]); 
writeln(out_file); 
end; 
end 
until not odd(status) ; 





(continued on next page) 
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Example 13-3 (Cont.) Using SOR Routines to Merge Three Input Files in a VAX Pascal Program 





if status <> ss$ endoffile then error (status); 


status := sorSend_sort; 
if not odd(status) then error(status); 


writeln( ‘merge successful.’ ); 


end. 





Example 13-4 is a VAX Pascal program demonstrating a sort operation 
using a record interface. 


Example 13-4 Using SOR Routines to Sort Records from Two Input Files in a VAX Pascal 
Program 





Pascal Program 
PROGRAM FILETORECORDSORT (OUTPUT, SORTOUT) ; 


(* This program calls SOR routines to read and sort records from 
two input files, (PASINPUT1.DAT and PASINPUT2.DAT) and to return 
sorted records to this program to be written to the output file, 
(TEMP.TMP). *) 


(* Declarations for external status codes, and data structures, such as 
the types S$UBYTE (an unsigned byte) and SUWORD (an unsigned word). *) 


CONST 
SS$_NORMAL = 1 


Il ss 


SS$ ENDOFFILE = %X870; 
SORSGK_RECORD = 1; 


SORSM_STABLE = 1; 
SORSM_SEQ CHECK = 4; 
SORSM_SIGNAL = 8; 
DSC$K_DTYPE T = 14; 


TYPE 
SUBYTE = [BYTE] 0..255; 
SUWORD = [WORD] 0..65535; 
CONST 
Numberofkeys = 1 ; (* Number of keys for this sort *) 
LRL = 131 ; (* Longest Record Length for output records *) 


(* Key orders *) 


Ascending = 0 ; 
Descending = 1 ; 


TYPE 
Keybufferblock= packed record 
: Keytype : SUWORD ; 
Keyorder : $UWORD ; 
Keyoffset : SUWORD ; 
Keylength : SUWORD 
end ; 


(* The keybuffer. Note that the field buffer is a one-component array in 
this program. This type definition would allow a multikeyed sort. *) 





(continued on next page) 
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Example 13-4 (Cont.) Using SOR Routines to Sort Records from Two Input Files in a VAX 
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Keybuffer= packed record 
Numkeys : SUWORD ; 
Blocks : packed array[1..Numberofkeys] OF Keybufferblock 
end ; 


(* The record buffer. This buffer will be used to hold the returned 
records from SORT. *) 


Recordbuffer = packed array[1..LRL] of char ; 


(* Name type for input and output files. A necessary fudge for %stdescr 
mechanism. *) 


nametype= packed array[1..13] of char ; 


VAR 
Sortout : text ; (* the output file *) 
Buffer : Keybuffer ; (* the actual keybuffer *) 
Sortoptions : integer ; (* flag for sorting options *) 
Sorttype : SUBYTE ; (* sorting process *) 
Numworkfiles : SUBYTE ; (* number of work files *) 
Status : integer ; (* function return status code *) 
Rec : Recordbuffer ; (* a record buffer *) 
Recordlength : SUWORD ; (* the returned record length *) 
Inputname: nametype ; (* input file name *) 
i: integer ; (* loop control variable *) 


(* function and procedure declarations *) 


(* Declarations of SORT functions *) 

(* Note that the following SORT routine declarations 
do not use all of the possible routine parameters. *) 

(* The parameters used MUST have all preceding parameters specified, 
however. *) 


FUNCTION SORSPASS_ FILES 
(SSTDESCR Inname : nametype ) 
INTEGER ; EXTERN ; 


FUNCTION SORSBEGIN_ SORT ( 
VAR Buffer : Keybuffer ; 
Lrlen : SUWORD ; 
VAR Sortoptions .: INTEGER ; 
SIMMED Filesize : INTEGER ; 
SIMMED Usercompare : INTEGER ; 
SIMMED Userequal : INTEGER ; 
VAR Sorttype : SUBYTE ; 
VAR Numworkfiles : SUBYTE ) 

INTEGER ; EXTERN ; 





(continued on next page) 
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FUNCTION SORSSORT_MERGE 
INTEGER ; EXTERN ; 


FUNCTION SORSRETURN_REC ( 
SSTDESCR Rec : Recordbuffer ; 
VAR Recordsize : SUWORD ) 

: INTEGER ; EXTERN ; 


FUNCTION SORSEND_SORT 
INTEGER ; EXTERN ; 
(* End of the SORT function declarations *) 


(* The CHECKSTATUS routine checks the return status for errors. *) 
(* If there is an error, write an error message and exit via sys$exit *) 
PROCEDURE CHECKSTATUS( var status : integer ) ; 


procedure sysSexit( status : integer ) ; extern ; 


begin (* begin checkstatus *) 
if odd(status) then 
begin 
writeln( ‘’ SORT unsuccessful. Error status = ’, status:8 hex ) ; 
SYSSEXIT( status ) ; 
end ; 
end ; (* end checkstatus *) 


(* end function and routine declarations *) 


BEGIN (* begin the main routine *) 


(* Initialize data for one 8-byte character key, starting at record 
offset 0, 3 work files, and the record sorting process *) 


Inputname := ’PASINPUT1.DAT’ ; 
WITH Buffer DO 
BEGIN 
Numkeys := 1; 
WITH Blocks[{1i] DO 
BEGIN 
Keytype := DSCSK_DTYPE_T ; (* Use VMS descriptor data types to 
define SORT data types. *) 
Keyorder := Ascending ; 
Keyoffset := 0; 
Keylength := 8 ; 
END; 
END; 
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Sorttype := SORSGK_RECORD ; (* Use the global SORT constant to 
define the sort process. *) 
Sortoptions := SORSM_STABLE ; (* Use the global SORT constant to 


define the stable sort option. *) 
Numworkfiles := 3 ; 


(* call the sort routines as a series of functions *) 


(* pass the first filename to SORT *) 
Status := SORSPASS FILES( Inputname ) ; 


(* Check status for error. *) 
CHECKSTATUS( Status ) ; 


(* pass the second filename to SORT *) 
Inputname := /PASINPUT2.DAT’ ; 


Status := SORSPASS FILES( Inputname ) ; 


(* Check status for error. *) 
CHECKSTATUS( Status ) ; 


(* initialize work areas and keys *) 
Status := SORSBEGIN_SORT( Buffer, 0, Sortoptions, 0, 0, 0, 
Sorttype, Numworkfiles ) ; 


(* Check status for error. *) 
CHECKSTATUS( Status ) ; 


(* sort the records *) 
Status := SORSSORT_MERGE ; 


(* Check status for error. *) 
CHECKSTATUS( Status ) ; 


(* Ready output file for writing returned records from SORT. *) 
OPEN( SORTOUT, ’TEMP.TMP’ ) ; 
REWRITE ( SORTOUT ) ; 


(* Now get the sorted records from SORT. *) 


Recordlength := 0 ; 
REPEAT 
Status := SORSRETURN_REC( Rec, Recordlength ) ; 
if odd( Status ) 
then (* if successful, write record to output file. *) 
begin 
for i := 1 to Recordlength do 
write( sortout, Rec[i] ) ; (* write each character *) 
writeln (sortout) ; (* end output line *) 
end; 


UNTIL not odd( Status ) ; 


(* If there was just no more data to be returned (eof) continue, otherwise 
exit with an error. *) 
if Status <> SS$ ENDOFFILE then 
CHECKSTATUS( Status ) ; 


(* The sort has been successful to this point. *) 


(* Close the output file *) 
CLOSE( sortout ) ; 





(continued on next page) 
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(* clean up work areas and files *) 
Status := SORSEND_SORT ; 


(* Check status for error. *) 
CHECKSTATUS( Status ); 


WRITELN (’SORT SUCCESSFUL’) ; 
END. 





SOR Routines 
The following pages describe the individual SOR routines. 
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SORS$BEGIN_MERGE Initialize a Merge Operation 


The SOR$BEGIN_MERGE routine initializes the merge operation by opening 
the input and output files and by providing the number of input files, the key 
specifications, and the merge options. 





FORMAT SOR$BEGIN_MERGE [key-buffer] [,/ri] 
[options] [,merge_order] 
[,user_compare] [,user_equal] 
[,user_input] [,context] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
_ CONDITION VALUES RETURNED. 





ARGUMENTS _ key_buffer 
VMS usage: vector_word_unsigned 
type: word (unsigned) 
access: read only 
mechanism: by reference 
Array of words describing the keys on which you plan to merge. The 
key_buffer argument is the address of an array containing the key 
descriptions. 


The first word of this array contains the number of keys described (up to 
255). Following the first word, each key is described (in order of priority) 
in blocks of four words. The four words specify the key’s data type, order, 
offset, and length, respectively. 


The first word of the block specifies the key’s data type. The following data 
types are accepted: 


DSC$K_DTYPE_Z Unspecified (uninfluenced by collating sequence) 
DSC$K_DTYPE_B Byte integer (signed) 

DSC$K_DTYPE_BU Byte (unsigned) 

DSC$K_DTYPE_W Word integer (signed) 

DSC$K_DTYPE_WU Word (unsigned) 

DSC$K_DTYPE_L Longword integer (signed) 

DSC$K_DTYPE_LU Longword (unsigned) 

DSC$K_DTYPE_Q Quadword integer (signed) 
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DSC$K_DTYPE_QU Quadword (unsigned) 


DSC$K_DTYPE_O Octaword integer (signed) 
DSC$K_DTYPE_OU Octaword (unsigned) 

DSC$K_DTYPE_F Single-precision floating 

DSC$K_DTYPE_D Double-precision floating 

DSC$K_DTYPE_G G-format floating 

DSC$K_DTYPE_H H-format floating 

DSC$K_DTYPE_T Text (may be influenced by collating sequence) 


DSC$K_DTYPE_NU Numeric string, unsigned 

DSC$K_DTYPE_NL Numeric string, left separate sign 
DSC$K_DTYPE_NLO Numeric string, left overpunched sign 
DSC$K_DTYPE_NR Numeric string, right separate sign 
DSC$K_DTYPE_NRO Numeric string, right overpunched sign 
DSC$K_DTYPE_NZ Numeric string, zoned sign 

DSC$K_DTYPE_P Packed decimal! string 

The VAX Procedure Calling and Condition Handling Standard, 


documented in the Introduction to VMS System Routines, describes each of 
these data types. 


The second word of the block specifies the key order: 0 for ascending order, 
1 for descending order. The third word of the block specifies the relative 
offset of the key in the record. (Note that the first byte in the record is at 
position 0.) The fourth word of the block specifies the key length in bytes 
(in digits for packed decimal—DSC$K_DTYPE_P). 


If you do not specify the key_buffer argument, you must pass either a 
key comparison routine or use a specification file to define the key. 


Irl 

VMS usage: word_unsigned 
type: word (unsigned) 
access: read only 


mechanism: by reference 

Length of the longest record that will be released for merging. The Irl 
argument is the address of a word containing the length. If the input file 
is on a disk, this argument is not required. It is required when you use 
the record interface. For VFC records, this length must include the length 
of the fixed-length portion of the record. 


options 

VMS usage: mask_longword 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Flags that identify merge options. The options argument is the address of 
a longword bit mask whose settings determine the merge options selected. 
The following table lists and describes the bit mask values available. 
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Flag Description 

SOR$M_STABLE Keeps records with equal keys in the same order as they 
appeared on input. 

SOR$M_EBCDIC Orders ASCII character keys according to EBCDIC collating 
sequence. No translation takes place. 

SOR$M_MULTI Orders character keys according to the multinational 


collating sequence, which collates the international 
character set. 

SOR$M_NOSIGNAL Returns a status code instead of signaling errors. (This is 
the default behavior.) 

SOR$M_NODUPS Omits records with duplicate keys. You cannot use this 
option if you specify your own equal-key routine. 

SOR$M_SEQ_CHECK _ Requests an “out of order” error return if an input file is not 
already in sequence. By default, this check is not done. 
You must request sequence checking if you specify an 
equal-key routine. 


All other bits in the longword are reserved and must be zero. 


merge_order 

VMS usage: byte_unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference 

Number of input streams to be merged. The merge_order argument is 
the address of a byte containing the number of files (1 through 10) to be 
merged. When you use the record interface on input, this argument is 
required. 


user_compare 

VMS usage: procedure 

type: procedure entry mask 

access: function call 

mechanism: by reference 

Routine that compares records to determine their merge order. The user_ 
compare argument is the address of the entry mask for this user-written 
routine. If you do not specify the key_buffer argument or if you define 
key information in a specification file, this argument is required. 


MERGE calls the comparison routine with five reference arguments— 
ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding to the addresses 
of the two records to be compared, the lengths of these two records, and 
the context longword. 


The comparison routine must return a 32-bit integer value: 
e -1 ifthe first record collates before the second 
¢ ifthe records collate as equal 


e 1if the first record collates after the second 
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user_equal 

VMS usage: procedure 

type: procedure entry mask 

access: function call 

mechanism: by reference 

Routine that resolves the merge order when records have duplicate keys. 
The user_equal argument is the address of the entry mask for this user- 
written routine. If you specify SOR$M_STABLE or SOR$M_NODUPS in 
the options argument, do not use this argument. 


MERGE calls the duplicate key routine with five reference arguments— 
ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding to the addresses 
of the two records that compare equally, the lengths of the two records 
that compare equally, and the context longword. 


The routine must return one of the following 32-bit condition codes. 


Code Description 


SOR$_DELETE1 Delete the first record from the merge. 
SOR$_DELETE2 Delete the second record from the merge. 
SOR$_DELBOTH Delete both records from the merge. 
SS$_NORMAL Keep both records in the merge. 


Any other failure value causes the error to be signaled or returned. Any 
other success value causes an undefined result. 


user_input 

VMS usage: procedure 

type: procedure entry mask 

access: function call 

mechanism: by reference 

Routine that releases records to the merge operation. The user_input 
argument is the address of the entry mask for this user-written routine. 
SOR$BEGIN_MERGE and SOR$RETURN_REC call this routine until all 
records have been passed. 


This input routine must read (or construct) a record, place it in a record 
buffer, store its length in an output argument, and then return control to 
MERGE. 


The input routine must accept the following four arguments: 
¢ <A descriptor of the buffer where the routine must place the record 


e A longword, passed by reference, containing the stream number from 
which to input a record (the first file is 1, the second 2, and so on) 


e Aword, passed by reference, where the routine must return the actual 
length of the record 


e The context longword, passed by reference 


The input routine must also return one of the following status values: 


e¢ SS$ NORMAL or any other success status causes the merge operation 
to continue. 
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e SS$ ENDOFFILE indicates that no more records are in the file. The 
contents of the buffer are ignored. 


e Any other error status terminates the merge operation and passes 
the status value back to the caller of SOR$BEGIN_MERGE or 
SOR$RETURN_REC. 


context 

VMS usage: context 

type: longword (unsigned) 
access: modify 


mechanism: by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
subsequent routine calls for the same operation, you must pass the context 
value that was supplied by SORT/MERGE. 





DESCRIPTION 


The SOR$BEGIN_MERGE routine initializes the merge process by 
passing arguments that provide the number of input streams, the key 
specifications, and any merge options. 


You must define the key by passing either the key buffer address argument 
or your own comparison routine address. (You can also define the key in a 
specification file and call the SOR$SPEC_FILE routine.) 


The SOR$BEGIN_MERGE routine initializes the merge process in the file, 
record, and mixed interfaces. For record interface on input, you must also 
pass the merge order, the input routine address, and the longest record 
length. For files not on disk, you must pass the longest record length. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 





CONDITION 
VALUES 
RETURNED 
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SS$_ NORMAL Success. 

SOR$_BADDTYPE invalid or unsupported CDD datatype. 

SOR$_BADLENOFF Length and offset must be multiples of 8 bits. 

SOR$_BADLOGIC Internal logic error detected. 

SOR$_BADOCCURS Invalid OCCURS clause. 

SOR$_BADOVRLAY Invalid overlay structure. 

SOR$_BADPROTCL Node is an invalid CDD object. 

SOR$_BAD_KEY Invalid key specification. 

SOR$_BAD_LRL Record length n greater than specified longest record 
length. 


SOR$_BAD_MERGE 
SOR$_BAD_ORDER 
SOR$_BAD_SRL 
SOR$_BAD_TYPE 
SOR$_CDDERROR 
SOR$_CLOSEIN 
SOR$_CLOSEOUT 
SOR$_COL_CHAR 
SOR$_COL_CMPLX 
SOR$_COL_PAD 
SOR$_COL_THREE 
SOR$_ENDDIAGS 
SOR$_ILLBASE 
SOR$_ILLLITERL 
SOR$_ILLSCALE 
SOR$_INCDIGITS 


SOR$_INCNODATA 
SOR$_INCNOKEY 
SOR$_IND_OVR 
SOR$_KEYAMBINC 
SOR$_KEYED 


SOR$_KEY_LEN 
SOR$_LRL_MISS 
SOR$_MISLENOFF 
SOR$_MISS_PARAM 
SOR$_MULTIDIM 
SOR$_NODUPEXC 


SOR$_NOTRECORD 
SOR$_NUM_KEY 
SOR$_OPENIN 
SOR$_OPENOUT 
SOR$_READERR 
SOR$_RTNERROR 
SOR$_SIGNCOMPQ 


SOR$_SORT_ON 
SOR$_SPCIVC 
SOR$_SPCIVD 
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Number of work files must be between 0 and 10. 
Merge input is out of order. 

Record length n is too short to contain keys. 
Invalid sort process specified. 

CDD error at node ‘name’. 

Error closing ‘file’ as input. 

Error closing ’ file’ as output. 

Invalid character definition. 

Coliating sequence is too complex. 

Invalid pad character. 

Cannot define 3-byte collating values. 
Completed with diagnostics. 

Nondecimal base is invalid. 

Record containing symbolic literals is unsupported. 
Nonzero scale invalid for floating-point data item. 


Number of digits is not consistent with the type or 
length of item. 


Include specification references no data, at line n. 
Include specification references no keys, at line n. 
Indexed output file must already exist. 

Key specification is ambiguous or inconsistent. 


Mismatch between SORT/MERGE keys and primary 
file key. 


Invalid key length, key number n, length n. 
Longest record length must be specified. 
Length and offset required. 

A required subroutine argument is missing. 
Invalid multidimensional OCCURS. 


Equal-key routine and no-duplicates option cannot 
both be specified. 


Node ‘name’ is a name, not a record definition. 
Too many keys specified. 

Error opening ’ file’ as input. 

Error opening ’ file’ as output. 

Error reading ‘file’ . 

Unexpected error status from user-written routine. 


Absolute Date and Time data type represented in 
one-second units. 


Sort or merge routines called in incorrect order. 
Invalid collating sequence specification at line n. 
Invalid data type at line n. 
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SOR$_SPCIVF 
SOR$_SPCIVI 
SOR$_SPCIVK 
SOR$_SPCIVP 
SOR$_SPCIVS 
SOR$_SPCIVX 
SOR$_SPCMIS 
SOR$_SPCOVR 
SOR$_SPCSIS 
SOR$_SRTIWA 


SOR$_STABLEEX 


SOR$_SYSERROR 
SOR$_UNDOPTION 
SOR$_UNSUPLEVL 
SOR$_WRITEERR 


Invalid field specification at line n. 

Invalid include or omit specification at line n. 
Invalid key or data specification at line n. 
Invalid sort process at line n. 

Invalid specification at line n. 

Invalid condition specification at line n. 
Invalid merge specification at line n. 
Overridden specification at line n. 

Invalid sort specification at line n. 


Insufficient space. The specification file is too 
complex. 


Equal-key routine and stable option cannot both be 
specified. 


System service error. 

Undefined option flag was set. 
Unsupported core level for record ‘name’. 
Error writing ‘file’. 
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SOR$BEGIN SORT Begin a Sort Operation 


The SOR$BEGIN_SORT routine initializes a sort operation by opening input 
and output files and by passing the key information and any sort options. 





FORMAT SOR$BEGIN_SORT  [key_buffer] [,/rl] [ options] 
[,file_alloc] [,user_compare] 
[,user_equal] [,sort_process] 
[,work_files] [,context] 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ key_buffer 
VMS usage: vector_word_unsigned 
type: word (unsigned) 
access: read only 
mechanism: by reference 
Array of words describing the keys on which you plan to sort. The 
key_buffer argument is the address of an array containing the key 
descriptions. 


The first word of this array contains the number of keys described (up to 
255). Following the first word, each key is described (in order of priority) 
in blocks of four words. The four words specify the key’s data type, order, 
offset, and length, respectively. 


The first word of the block specifies the data type of the key. The following 
data types are accepted: 


DSC$K_DTYPE_Z Unspecified (uninfluenced by collating sequence) 
DSC$K_DTYPE_B Byte integer (signed) 

DSC$K_DTYPE_BU Byte (unsigned) 

DSC$K_DTYPE_W Word integer (signed) 

DSC$K_DTYPE_WU Word (unsigned) 

DSC$K_DTYPE_L Longword integer (signed) 

DSC$K_DTYPE_LU Longword (unsigned) 

DSC$K_DTYPE_Q Quadword integer (signed) 


DSC$K_DTYPE_QU Quadword (unsigned) 
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DSC$K_DTYPE_O Octaword integer (signed) 
DSC$K_DTYPE_OU Octaword (unsigned) 

DSC$K_DTYPE_F Single-precision floating 

DSC$K_DTYPE_D Double-precision floating 

DSC$K_DTYPE_G G-format floating 

DSC$K_DTYPE_H H-format floating 

DSC$K_DTYPE_T Text (may be influenced by collating sequence) 


DSC$K_DTYPE_NU Numeric string, unsigned 

DSC$K_DTYPE_NL Numeric string, left separate sign 
DSC$K_DTYPE_NLO Numeric string, left overpunched sign 
DSC$K_DTYPE_NR Numeric string, right separate sign 
DSC$K_DTYPE_NRO Numeric string, right overpunched sign 
DSC$K_DTYPE_NZ Numeric string, zoned sign 

DSC$K_DTYPE_P Packed decimal string 

The VAX Procedure Calling and Condition Handling Standard, 


documented in the Introduction to VMS System Routines, describes each of 
these data types. 


The second word of the black specifies the key order: 0 for ascending order, 
1 for descending order. The third word of the block specifies the relative 
offset of the key in the record. Note that the first byte in the record is at 
position 0. The fourth word of the block specifies the key length in bytes 
(in digits for packed decimal—DSC$K_DTYPE_P). 


The key_buffer argument specifies the address of the key buffer in the 
data area. If you do not specify this argument, you must either pass a key 
comparison routine or use a specification file to define the key. 


Irl 

VMS usage: word_unsigned 
type: word (unsigned) 
access: read only 


mechanism: by reference 

Length of the longest record that will be released for sorting. The Irl 
argument is the address of a word containing the length. This argument 
is not required if the input files are on disk but is required when you use 
the record interface. For VFC records, this length must include the length 
of the fixed-length portion of the record. 


options 

VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Flags that identify sort options. The options argument is the address of 
a longword bit mask whose settings determine the merge options selected. 
The following table lists and describes the bit mask values available: 
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Flags Description 
SOR$M_STABLE Keeps records with equal keys in the same order in which 


they appeared on input. With multiple input files that have 
records that collate as equal, records from the first input file 
are placed before the records from the second input file, and 


so on. 
SOR$M_EBCDIC Orders ASCII character keys according to EBCDIC collating 
sequence. No translation takes place. 
SORS$M_MULTI Orders character keys according to the multinational collating 


sequence, which collates the international character set. 


SOR$M_NOSIGNAL _ Returns the condition code instead of signaling an error. The 
default is SOR$M_NOSIGNAL. 


SOR$M_NODUPS Omits records with duplicate keys. You cannot use this option 
if you specify your own equal-key routine. 


All other bits in the longword are reserved and must be zero. 


file_alloc 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Input file size in blocks. The file_alloc argument is the address of a 
longword containing the size. This argument is never required because, 
by default, SORT uses the allocation of the input files. If you are using 
the record interface or if the input files are not on disk, the default is 1000 
blocks. 


However, you can use this optional argument to improve the efficiency of 
the sort by adjusting the amount of resources the sort process allocates. 


user_compare 

VMS usage: procedure 

type: procedure entry mask 

access: function call 

mechanism: by reference 

User-written routine that compares records to determine their sort order. 
The user_compare argument is the address of the entry mask for this 
user-written routine. If you do not specify the key_buffer argument 

or if you define key information in a specification file, this argument is 
required. 


SORT/MERGE calls the comparison routine with five reference 
arguments—ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding 
to the addresses of the two records to be compared, the lengths of these 
two records, and the context longword. 


The comparison routine must return a 32-bit integer value: 
e -1 if the first record collates before the second 
¢ ifthe records collate as equal 


e 1if the first record collates after the second 
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user_equal 

VMS usage: procedure 

type: procedure entry mask 

access: function call 

mechanism: by reference 

User-written routine that resolves the sort order when records have 
duplicate keys. The user_equal argument is the address of the entry 
mask for this user-written routine. If you specify SOR$M_STABLE or 
SOR$M_NODUPS in the options argument, do not use this argument. 


SORT/MERGE calls the duplicate key routine with five reference 
arguments—ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding 
to the addresses of the two records that compare equally, the lengths of 
the two records that compare equally, and the context longword. 


The routine must return one of the following 32-bit integer condition codes: 


Code Description 


SOR$_DELETE1 Delete the first record from the sort. 
SOR$_DELETE2 Delete the second record from the sort. 
SOR$_DELBOTH Delete both records from the sort. 
SS$_NORMAL Keep both records in the sort. 


Any other failure value causes the error to be signaled or returned. Any 
other success value causes an undefined result. 


sort_pr ocess 

VMS usage: byte_unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference 

Code indicating the type of sort process. The sort_process argument 
is the address of a byte whose value indicates whether the sort type is 
record, tag, index, or address. The default is record. If you select the — 
record interface on input, you can use only a record sort process. 


To specify a byte containing the value for the type of sort process you 
want, enter one of the following: 


¢ SOR$GK_RECORD (record sort) 

¢ SOR$GK_TAG (tag sort) 

e SOR$GK_ADDRESS (address sort) 
e SOR$GK_INDEX (index sort) 


work_files 

VMS usage: byte_unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference 

Number of work files to be used in the sorting process. The work_files 
argument is the address of a byte containing the number of work files; 
permissible values range from 0 through 10. 
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By default, SORT creates two temporary work files when it needs them 
and determines their size from the size of your input files. By increasing 
the number of work files, you can reduce their individual size so that each 
fits into less disk space. You can also assign each of them to different 
disk-structured devices. 


context 

VMS usage: context 

type: longword (unsigned) 
access: write only 


mechanism: by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
subsequent routine calls for the same operation, you must pass the context 
value supplied by SORT/MERGE. 





DESCRIPTION 


The SOR$BEGIN_SORT routine initializes the sort process by setting up 
sort work areas and provides key specification and sort options. 


Specify the key information with the key_buffer argument, with the 
user_compare argument, or in a specification file. If no key information 
is specified, the default (character for the entire record) is used. 


You must use the SOR$BEGIN_SORT routine to initialize the sort process 
for the file, record, and mixed interfaces. For record interface on input, 
you must use the Irl (longest record length) argument. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIBSMATCH_COND. 





CONDITION 
VALUES 
RETURNED 


SS$_NORMAL Success. 
SOR$_BADLOGIC Internal logic error detected. 
SOR$_BAD_KEY Invalid key specification. 


SOR$_BAD_LRL Record length n greater than specified longest record 
length. 


SOR$_BAD_MERGE Number of work files must be between 0 and 10. 
SOR$_BAD_TYPE Invalid sort process specified. 
SOR$_ENDDIAGS Completed with diagnostics. 

SOR$_INSVIRMEM Insufficient virtual memory. 

SOR$_KEYAMBINC Key specification is ambiguous or inconsistent. 
SOR$_KEY_LEN Invalid key length, key number n, length n. 
SOR$_LRL_MISS Longest record length must be specified. 
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SOR$_NODUPEXC 


SOR$_NUM_KEY 
SOR$_RTNERROR 
SOR$_SORT_ON 
SOR$_STABLEEXC 


SOR$_SYSERROR 
SOR$_UNDOPTION 


Equal-key routine and no-duplicates option cannot 
both be specified. 


Too many keys specified. 
Unexpected error status from user-written routine. 
Sort or merge routine called in incorrect order. 


Equal-key routine and stable option cannot both be 
specified. 


System service error. 
Undefined option flag was set. 
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SORS$DTYPE Define Data Type 


The SOR$DTYPE routine defines a key data type that is not normally 
supported by SORT/MERGE. This routine returns a key data type code 
that can be used in the key_buffer argument to SOR$BEGIN_SORT or 
SOR$BEGIN_MERGE to describe special key data types (such as extended 
data types and NCS collating sequences). 





FORMAT 


SOR$DTYPE [context], dtype_code, usage, p1 





RETURNS 


VMS usage: Cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
subsequent routine calls for the same operation, you must pass the context 
value supplied by SORT/MERGE. 


dtype_code 

VMS usage: word_unsigned 

type: word (unsigned) 

access: write only 

mechanism: by reference 

Returned key data type code. The dtype_code argument is the address of 
a word into which SORT/MERGE writes the key data type code that can be 
used in the key_buffer argument to SOR$SBEGIN_SORT or SOR$BEGIN_ 
MERGE. 


usage 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 
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Address of a longword containing a code that indicates the interpretation 
of the pl argument. The following table lists and describes the valid usage 
codes. 


Flag Description 


SOR$K_ROUTINE The p1 argument should be interpreted as the address of 
the entry mask of a routine that SORT/MERGE will call 
to compare keys described by the dtype_code returned 
by the call to SOR$DTYPE. 

SOR$K_NCS_TABLE The p1 argument should be interpreted as the address 
of a collating sequence identification returned by a call 
to NCS$GET_CS. SORT/MERGE will use this collating 
sequence to compare keys described by the dtype_code 
returned by the call to SOR$DTYPE. 


If SOR$K_ROUTINE is returned, SORT/MERGE will call this routine with 
five reference arguments—ADRS1, ADRS2, LENG1, LENG2, CNTX— 
corresponding to the addresses of the two keys to be compared, the lengths 
of the two keys, and the context longword. 


The comparison routine must return a 32-bit integer value: 
e -1 if the first key collates before the second 

¢ 0 if the keys collate as equal 

¢ +1 if the first key collates after the second 


p1 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Address of an entry mask of a routine or the address of a collating 
sequence identification, depending on the usage argument. 





Call SOR$DTYPE to define a key data type not normally supported by 
SORT/MERGE. 


If your SORT/MERGE application needs to compare dates (for example) 
that are stored in text form and that is the only key in the records, then 
use the user_compare argument to SOR$BEGIN_SORT or SOR$BEGIN_ 
MERGE. However, if the records contain several keys besides the dates 

in text form, it may be easier to call SOR$DTYPE to allocate a key data 
type code that can then be used in the the key_buffer argument to 
SOR$BEGIN_SORT or SORSBEGIN_MERGE. 


If your SORT/MERGE application has a string key that should be collated 
by a collating sequence defined by the VMS National Character Set (NCS) 
Utility, the NCS$GET_CS routine can be used to fetch the collating 
sequence definition, and SOR$DTYPE can be called to allocate a key data 
type code for the collating sequence. This key data type code can then be 
used to describe keys that should be compared by this collating sequence. 
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SORS$DTYPE 
Sait tla SS$_NORMAL Success. 
RETURNED SOR$_SORT_ON Sort or merge routine called in incorrect order. 
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SOR$END SORT End a Sort Operation 


The SOR$END_SORT routine does cleanup functions, such as closing files 
and releasing memory. 














FORMAT SOR$END SORT [context] 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENT context 
VMS usage: context 
type: longword 
access: write only 
mechanism: by reference 
Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
subsequent routine calls for the same operation, you must pass the context 
value supplied by SORT/MERGE. 

DESCRIPTION The SOR$END_SORT routine ends a sort or merge operation, either at the 
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end of a successful process or between calls because of an error. If an error 
status is returned, you must call SOR$END_SORT to release all allocated 
resources. In addition, this routine can be called at any time to close files 

and release memory. 


The value of the optional context argument is cleared when the 
SOR$END_SORT routine completes its operation. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIBSMATCH_COND. 
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CONDITION 
VALUES 
RETURNED 


SS$_NORMAL 
SOR$_CLOSEIN 
SOR$_CLOSEOUT 
SOR$_ENDDIAGS 
SOR$_END_SORT 
SOR$_SYSERROR 


Success. 

Error closing ‘file’ as input. 

Error closing ‘file’ as output. 

Completed with diagnostics. 

SORT/MERGE terminated, context = ‘context’. 
System service error. 
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SOR$PASS FILES Pass File Names 


The SOR$PASS_FILES routine passes the names of input and output files 
and output file characteristics to SORT or MERGE. 











FORMAT SOR$PASS FILES [inp_desc] [,out_desc] [,org] [,rfm] 
[,bks] [bls] [| mrs] [,alq] [,fop] [| fsz] 
[,context] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS = inp_desc 
VMS usage: char_string 
type: character-coded text string 
access: read only 
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mechanism: by descriptor 

Input file specification. The inp_desc argument is the address of a 
descriptor pointing to the file specification. In the file interface, you 
must call SOR$PASS_FILES to pass SORT the input file specifications. 
For multiple input files, call SOR$PASS_FILES once for each input file, 
passing one input file specification descriptor each time. 


In the mixed interface, if you are using the record interface on input, pass 
only the output file specification; do not pass any input file specifications. 
If you are using the record interface on output, pass only the input file 
specifications; do not pass an output file specification or any of the optional 
output file arguments. . 


out_desc 


VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor 

Output file specification. The out_desc argument is the address of a 
descriptor pointing to the file specification. In the file interface, when 
you call SOR$PASS_FILES, you must pass the output file specification. 
Specify the output file specification and characteristics only once, as part 
of the first call, as in the following: 


Call SORSPASS_FILES (Input1, Output) 
Call SORSPASS FILES (Input2) 
Call SORSPASS_ FILES (Input3) 
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In the mixed interface, if you are using the record interface on input, pass 
only the output file specification; do not pass any input file specifications. 
If you are using the record interface on output, pass only the input file 
specifications; do not pass an output file specification or any of the optional 
output file arguments. . 


org 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 

File organization of the output file, if different from the input file. The org 
argument is the address of a byte whose value specifies the organization of 
the output file; permissible values include the following: 


FABSC_SEQ 
FABSC_REL 
FABSC_IDX 


For the record interface on input, the default value is sequential. For the 
file interface, the default value is the file organization of the first input file 
for record or tag sort and sequential for address and index sort. 


For more information about the FAB fields, see the VMS Record 
Management Services Manual. 


rfm 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 

Record format of the output file, if different from the input file. The rfm 
argument is the address of a byte whose value specifies the record format 
of the output file; permissible values include the following: 


FABSC_FIX 
FABSC_ VAR 
FABSC_VFC 


For the record interface on input, the default value is variable. For the 
file interface, the default value is the record format of the first input 
file for record or tag sort and fixed format for address or index sort. For 
the mixed interface with record interface on input, the default value is 
variable format. 


bks 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 

Bucket size of the output file, if different from the first input file. The bks 
argument is the address of a byte containing this size. Use this argument 
with relative and indexed-sequential files only. If the bucket size of the 
output file is to differ from that of the first input file, specify a byte to 
indicate the bucket size. Acceptable values are from 1 to 32. If you do 
not pass this argument—and the output file organization is the same as 
that of the first input file—the bucket size defaults to the value of the first 
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input file. If the file organizations differ or if the record interface is used 
on input, the default value is 1 block. 


bls 

VMS usage: word_unsigned 
type: word (unsigned) 
access: read only 


mechanism: by reference 

Block size of a magnetic tape output file. The bls argument is the address 
of a word containing this size. Use this argument with magnetic tapes 
only. Permissible values range from 20 to 65,532. However, to ensure 
compatibility with non-Digital systems, ANSI standards require that the 
block size be less than or equal to 2048. 


The block size defaults to the block size of the input file magnetic tape. If 
the input file is not on magnetic tape, the output file block size defaults to 
the size used when the magnetic tape was mounted. 


mrs 

VMS usage: word_unsigned 
type: word (unsigned) 
access: — read only 


mechanism: by reference 
Maximum record size for the output file. The mrs argument is the address 
of a word specifying this size. Following are acceptable values for each 


type of file. 

File Organization Acceptable Value 
Sequential 0 to 32,767 
Relative 0 to 16,383 
Indexed sequential 0 to 16,362 


If you omit this argument or if you specify a value of 0, SORT does not 
check maximum record size. 


If you do not specify this argument, the default is based on the output 
file organization and format, unless the organization is relative or the 
format is fixed. The longest output record length is based on the longest 
calculated input record length, the type of sort, and the record format. 


alq 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

Number of preallocated output file blocks. The alq argument is the 
address of a longword specifying the number of blocks you want to 
preallocate to the output file. Acceptable values range from 1 to 
4,294,967,295. 
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Pass this argument if you know your output file allocation will be larger 
or smaller than that of your input files. The default value is the total 
allocation of all the input files. If the allocation cannot be obtained for any 
of the input files or if record interface is used on input, the file allocation 
defaults to 1000 blocks. 


fop 

VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 


mechanism: by reference 

File-handling options. The fop argument is the address of a longword 
whose bit settings determine the options selected. For a list of valid 
options, see the description of the FAB$L_FOP field in the VMS Record 
Management Services Manual. By default, only the DFW (deferred write) 
option is set. If your output file is indexed, you should set the CIF (create 
if) option. 


fsz 

VMS usage: byte_unsigned 
type: byte (unsigned) 
access: read only 


mechanism: by reference 

Size of the fixed portion of VFC records. The fsz argument is the address 

of a byte containing this size. If you do not pass this argument, the default 

is the size of the fixed portion of the first input file. If you specify the VEC 
size as 0, RMS defaults the value to 2 bytes. 


context 


VMS usage: context 

type: longword (unsigned) 

access: write only 

mechanism: by reference 

Value that distinguishes between multiple concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
subsequent routine calls for the same operation, you must pass the context 
value supplied by SORT/MERGE. 





DESCRIPTION 


The SOR$PASS_FILES routine passes input and output file specifications 
to SORT. The SOR$PASS_FILES routine must be repeated for multiple 
input files. The output file name string and characteristics should be 
specified only in the first call to SOR$PASS_FILES. 


This routine also accepts optional arguments that specify characteristics 
for the output file. By default, the output file characteristics are the same 
as the first input file; specified output file characteristics are used to 
change these defaults. 
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Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIB${MATCH_COND. 





CONDITION 
VALUES SS$_NORMAL Success. 
R SOR$_DUP_OUTPUT Ouiput file has already been specified. 
ETURNED SOR$_ENDDIAGS Completed with diagnostics. 
SOR$_INP_FILES Too many input files specified. 
SOR$_SORT_ON Sort or merge routine called in incorrect order. 
SOR$_SYSERROR System service error. 
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SOR$RELEASE REC Pass One Record to Sort 


The SOR$RELEASE_REC routine is used with the record interface to pass 
one input record to SORT or MERGE. 





FORMAT 


SOR$RELEASE REC desc [,context] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


desc 

VMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor 

Input record buffer. The dese argument is the address of a descriptor 
pointing to the buffer containing the record to be sorted. If you use the 
record interface, this argument is required. 


context 


VMS usage: context 

type: longword 

access: modify 

mechanism: by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
subsequent routine calls for the same operation, you must pass the context 
value supplied by SORT/MERGE. 





DESCRIPTION 


Call SOR$RELEASE_REC to pass records to SORT or MERGE with the 
record interface. SOR$RELEASE_REC must be called once for each record 
to be sorted. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIBSMATCH_COND. 
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CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL 
SOR$_BADLOGIC 
SOR$_BAD_LRL 


SOR$_BAD_SRL 
SOR$_ENDDIAGS 
SOR$_EXTEND 
SOR$_MISS_PARAM 
SOR$_NO_WRK 


SOR$_OPENOUT 
SOR$_OPERFAIL 
SOR$_OPREPLY 
SOR$_READERR 
SOR$_REQ_ALT 
SOR$_RTNERROR 
SOR$_SORT_ON 
SOR$_SYSERROR 
SOR$_USE_ALT 
SOR$_WORK_DEV 


Success. 
Internal logic error detected. 


Record length n greater than longest specified record 
length. 


Record length n too short to contain keys. 
Completed with diagnostics. 

Unable to extend work file for needed space. 
The dese argument is missing. 


Work files required, cannot do sort in memory as 
requested. 


Error opening ’ file’ as output. 

Error requesting operator service. 

Operator reply is ’ reply’. 

Error reading ‘file’ . 

Specify alternate name’ file (or nothing to try again). 
Unexpected error status from user-written routine. 
Sort or merge routines called in incorrect order. 
System service error. 

Using alternate file ‘name’. 


Work file “name’ must be on random access local 
device. 
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SOR$RETURN REC Return One Sorted Record 


The SOR$RETURN_REC routine is used with the record interface to return 
one sorted or merged record to a program. 











FORMAT SOR$RETURN_REC desc /,length] [,context] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 
ARGUMENTS '~=_ desc 
VMS usage: char_string 
type: character-coded text string 
access: write only 


mechanism: by descriptor 
Output record buffer. The dese argument is the address of a descriptor 
pointing to the buffer that receives the sorted or merged record. 


length 

VMS usage: word_unsigned 
type: word (unsigned) 
access: write only 


mechanism: by reference 
Length of the output record. The length argument is the address of a 
word receiving the length of the record returned from SORT/MERGE. 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
subsequent routine calls for the same operation, you must pass the context 
value supplied by SORT/MERGE. 
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DESCRIPTION Call the SOR$RETURN_REC routine to release the sorted or merged 
records to a program. Call this routine once for each record to be returned. 


SOR$RETURN_REC places the record into a record buffer that you set 
up in the program’s data area. After SORT has successfully returned all 
the records to the program, it returns the status code SS$_ENDOFFILE, 
which indicates that there are no more records to return. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIBSMATCH_COND. 





CONDITION 
aint a 5 SOR$_BADLOGIC 


SOR$_ENDDIAGS 
SOR$_EXTEND 
SOR$_MISS_PARAM 
SOR$_OPERFAIL 
SOR$_OPREPLY 
SOR$_READERR 
SOR$_REQ_ALT 


SOR$_RTNERROR 
SOR$_SORT_ON 
SOR$_SYSERROR 
SOR$_USE_ALT 
SOR$_WORK_DEV 
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Success. 

Internal logic error detected. 

Completed with diagnostics. 

Unable to extend work file for needed space. 

A required subroutine argument is missing. 

Error requesting operator service. 

Operator reply is ’ reply’. 

Error reading ‘file’ . 

Specify alternate ‘name’ file (or nothing to simply try 
again). 

Unexpected error status from user-written routine. 
Sort or merge routines called in incorrect order. 
System service error. 

Using alternate file ‘name’. 


Work file “name’ must be on random access local 
device. 
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SOR$SORT_MERGE Sort 


The SOR$SORT_MERGE routine sorts the input records. 














FORMAT SOR$SORT_MERGE [context] 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENT context 
VMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
subsequent routine calls for the same operation, you must pass the context 
value supplied by SORT/MERGE. 

DESCRIPTION After you have passed either the file names or the records to SORT, call 


the SOR$SORT_MERGE routine to sort the records. For file interface 

on input, the input files are opened and the records are released to the 
sort. For the record interface on input, the record must have already been 
released (by calls to SORS6RELEASE_REC). For file interface on output, 
the output records are reformatted and directed to the output file. For the 
record interface on output, SOR$RELEASE_REC must be called to get the 
sorted records. 


Some of the return values are used with different severities depending 
on whether SORT/MERGE can recover. Thus, if you want to check for a 
specific status, you should use LIBS MATCH_COND. 
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CONDITION 
VALUES 
RETURNED 
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SS$_NORMAL 
SOR$_BADDTYPE 


SOR$_BADLENOFF © 


SOR$_BADLOGIC 
SOR$_BADOCCURS 
SOR$_BADOVRLAY 
SOR$_BADPROTCL 
SOR$_BAD_LRL 


SOR$_BAD_TYPE 
SOR$_CDDERROR 
SOR$_CLOSEIN 
SOR$_CLOSEOUT 
SOR$_COL_CHAR 
SOR$_COL_CMPLX 
SOR$_COL_PAD 
SOR$_COL_THREE 
SOR$_ENDDIAGS 
SOR$_EXTEND 
SOR$_ILLBASE 
SOR$_ILLLITERL 
SOR$_ILLSCALE 
SOR$_INCDIGITS 


SOR$_INCNODATA 
SOR$_INCNOKEY 


SOR$_IND_OVR 
SOR$_KEYED 


SOR$_LRL_MISS 
SOR$_MISLENOFF 
SOR$_MULTIDIM 
SOR$_NOTRECORD 
SOR$_NO_WRK 


SOR$_OPENIN 

SOR$_OPENOUT 
SOR$_OPERFAIL 
SOR$_OPREPLY 


Success. 

Invalid or unsupported CDD data type. 
Length and offset must be multiples of 8 bits. 
Internal logic error detected. 


‘Invalid OCCURS clause. 


Invalid overlay structure. 
Node is an invalid CDD object. 


Record length n greater than longest specified record 
length. 


Invalid sort process specified. 

CDD error at node ‘name’. 

Error closing ‘file’ as input. 

Error closing ‘file’ as output. 

Invalid character definition. 

Collating sequence is too complex. 

Invalid pad character. 

Cannot define 3-byte collating values. 
Completed with diagnostics. 

Unable to extend work file for needed space. 
Nondecimal base is invalid. 

Record containing symbolic literals is unsupported. 
Nonzero scale invalid for floating-point data item. 


Number of digits is inconsistent with the type or length 
of item. 


Include specification references no ‘data’ keyword, 
at line n. 


Include specification references no ‘keys’ keyword, 
at line n. 


Indexed output file must already exist. 


Mismatch between SORT/MERGE keys and primary 
file key. 


Longest record length must be specified. 

Length and offset required. 

Invalid multidimensional OCCURS. 

Node ‘name’ is a name, not a record definition. 


Work files required, cannot do sort in memory as 
requested. 


Error opening / file’ as input. 
Error opening ‘file’ as output. 
Error requesting operator service. 
Operator reply is ’ reply’. 


SOR$_READERR 
SOR$_REQ_ALT 
SOR$_RTNERROR 
SOR$_SIGNCOMPQ 


SOR$_SORT_ON 
SOR$_SPCIVC 
SOR$_SPCIVD 
SOR$_SPCIVF 
SOR$_SPCIVI 
SOR$_SPCIVK 
SOR$_SPCIVP 
SOR$_SPCIVS 
SOR$_SPCIVX 
SOR$_SPCMIS 
SOR$_SPCOVR 
SOR$_SPCSIS 
SOR$_SRTIWA 
SOR$_SYSERROR 
SOR$_UNSUPLEVL 
SOR$_USE_ALT 
SOR$_WORK_DEV 


SOR$_WRITEERR 
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Error reading ‘file’. 
Specify alternate ‘name’ file (or nothing to try again). 
Unexpected error status from user-written routine. 


Absolute Date and Time data type represented in 
one-second units. 


Sort or merge routines called in incorrect order. 
Invalid collating sequence specification, at line n. 
Invalid data type, at line n. 

Invalid field specification, at line n. 

Invalid include or omit specification, at line n. 
Invalid key or data specification, at line n. 

Invalid sort process, at line n. 

Invalid specification, at line n. 

Invalid condition specification, at line n. 

invalid merge specification, at line n. 

Overridden specification, at line n. 

Invalid sort specification, at line n. 

Insufficient space. Specification file is too complex. 
System service error. 

Unsupported core level for record ‘name’. 
Using alternate file ‘name’. 


Work file “name’ must be on random access local 
device. 


Error writing ‘file’. 
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SORS$SPEC FILE Pass a Specification File Name 


The SOR$SPEC_FILE routine is used to pass a specification file or 
specification text to a sort or merge operation. 








FORMAT SOR$SPEC FILE [spec_file] [,spec_buffer] [,context] 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS __ spec _file 
VMS usage: char_string 
type: character-coded text string 
access: read-only 
mechanism: by descriptor 
Specification file name. The spec_file argument is the address of a 
descriptor pointing to the name of a file that contains the text of the 
options requested for the sort or merge. The specification file name string 
and the specification file buffer arguments are mutually exclusive. 


spec_buffer 

VMS usage: char_string 

type: character-coded text string 

access: read-only 

mechanism: by descriptor 

Specification text buffer. The spec_buffer argument is the address of a 
descriptor pointing to a buffer containing specification text. This text has 
the same format as the text within the specification file. The specification 
ve ee string and the specification file buffer arguments are mutually 
exclusive. 


context 

VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
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subsequent routine calls for the same operation, you must pass the context 
value supplied by SORT/MERGE. 





DESCRIPTION Call SOR$SPEC_FILE to pass a specification file name or a buffer with 
specification text to a sort or merge operation. Through the use of a 
specification file, you can selectively omit or include particular records 
from the sort or merge operation and specify the reformatting of the 
output records. (See the Sort Utility in the VMS Sort/Merge Utility 
Manual for a complete description of specification files.) 


If you call the SOR$SPEC_FILE routine, you must do so before you call 
any other routines. You must pass either the spec_file or spec_buffer 
argument, but not both. 


Some of the return condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIBS{MATCH_COND. 





CONDITION SOR$_ENDDIAGS Completed with diagnosti 
ompleted with diagnostics. 
VALUES : igre 
RETURNED SOR$_SORT_ON Sort or merge routine called in incorrect order. 
SOR$_SYSERROR System service error. 
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SORS$STAT 


SORS$STAT Obtain a Statistic 





FORMAT 





RETURNS 





ARGUMENTS 
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The SOR$STAT routine returns one statistic about the sort or merge operation 


to the user program. 


SOR$STAT code ,result [,context] 


VMS usage: cond_value 


type: 
access: 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 


longword (unsigned) 
write only 
mechanism: by value 


CONDITION VALUES RETURNED. 


code 


VMS usage: longword_unsigned 


type: 
access: 


longword (unsigned) 
read only 


mechanism: by reference 


SORT/MERGE statistic code. The code argument is the address of 
a longword containing the code that identifies the statistic you want 
returned in the result argument. The following values are accepted: 


Code 


SOR$K_IDENT 
SOR$K_REC_INP 
SOR$K_REC_SOR 
SOR$K_REC_OUT 
SOR$K_LRL_INP 
SOR$K_LRL_INT 
SOR$K_LRL_OUT 
SOR$K_NODES 
SOR$K_INI_RUNS 
SOR$K_MRG_ORDER 
SOR$K_MRG_PASSES 
SOR$K_WRK_ALQ 


Description 


Address of ASCII string for version number 


Number of records input 
Records sorted 
Records output 


Longest Record Length (LRL) for input 


Internal LRL 

LRL for output 

Nodes in sort tree 
Initial dispersion runs 
Maximum merge order 
Number of merge passes 
Work file allocation 
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Code Description 
SOR$K_MBC_INP Multiblock count for input 
SOR$K_MBC_OUT Multiblock count for output 
SOR$K_MBF_INP Multibuffer count for input 
SOR$K_MBF_OUT Multibuffer count for output 


Note that performance statistics (such as direct I/O, buffered I/O, 

and elapsed and CPU times) are not available because user-written 
routines may affect those values. However, they are available if you call 
LIB$GETJPI. 


result 

VMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 


mechanism: by reference 

SORT/MERGE statistic value. The result argument is the address of 
a longword into which SORT/MERGE writes the value of the statistic 
identified by the code argument. 


context 


VMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE 
operations. The context argument is the address of a longword containing 
the context value. When your program makes its first call to a SORT 
/MERGE routine for a particular sort or merge operation, the context 
longword must equal zero. SORT/MERGE then stores a value in the 
longword to identify the operation just initiated. When you make 
subsequent routine calls for the same operation, you must pass the context 
value supplied by SORT/MERGE. 





DESCRIPTION 


The SOR$STAT routine returns one statistic about the sort or merge 
operation to your program. You can call the SOR$STAT routine at any 
time while the sort or merge is active. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to 
check for a specific status, you should use LIB${MATCH_COND. 





CONDITION 
VALUES 
RETURNED 


SOR$_ENDDIAGS Completed with diagnostics. 
SOR$_MISS_PARAM A required subroutine argument is missing. 
SOR$_NYI Functionality is not yet implemented. 
SOR$_SYSERROR System service error. 
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This chapter describes callable VAX Text Processing (VAXTPU) Utility 
Routines. It describes the purpose of the VAXTPU callable routines, the 
parameters for the routine call, and the primary status returns. The 
parameter in the call syntax represents the object that you pass to a 
VAXTPU routine. Each parameter description lists the data type and 
the passing mechanism for the object. The data types are standard VMS 
data types. The passing mechanism indicates how the parameter list is 
interpreted. 


14.1 Introduction to VAXTPU Routines 


Callable VAXTPU Routines make VAXTPU accessible from within other 
VAX languages and applications. VAXTPU can be called from a program 
written in any VAX language that generates calls using the VAX Procedure 
Calling and Condition Handling Standard. You can also call VAXTPU from 
VMS utilities, for example, MAIL. Callable VAXTPU lets you perform text 
processing functions within your program. 


Callable VAXTPU consists of a set of callable routines that resides in the 
VAXTPU shareable image, TPUSHR.EXE. You access callable VAXTPU by 
linking against this shareable image, which includes the callable interface 
routine names and constants. As with the DCL-level VAXTPU interface, 
you can use files for input to and output from callable VAXTPU. You 

can also write your own routines for processing file input, output, and 
messages. 


This chapter is written for system programmers who are familiar with the 
following: 


¢ The VAX Procedure Calling and Condition Handling Standard 
¢ The VMS Run-Time Library (RTL) 


e The precise manner in which data types are represented on a VAX 
computer 


e The method for calling routines written in a language other than the 
one you are using for the main program 


The calling program must ensure that parameters passed to a called 
procedure, in this case VAXTPU, are of the type and form that the 
VAXTPU procedure accepts. 


The VAXTPU routines described in this chapter return condition values 
indicating the routine’s completion status. When comparing a returned 
condition value with a test value, you should use the LIB$MATCH routine 
from the Run-Time Library. Do not test the condition value as if it were a 
simple integer. 
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14.1.1 Two Interfaces to Callable VAXTPU 
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There are two interfaces you can use to access callable VAXTPU: the 
simplified callable interface and the full callable interface. 


Simplified Callable Interface 


The easiest way to use callable VAXTPU is to use the simplified callable 
interface. VAXTPU provides two alternative routines in its simplified 
callable interface. These routines in turn call additional routines that do 
the following: 


e Initialize the editor 
¢ Provide the editor with the parameters necessary for its operation 
¢ Control the editing session 


¢ Perform error handling 


When using the simplified callable interface, you can use the TPU$TPU 
routine to specify a VMS command line for VAXTPU, or you can call the 
TPU$EDIT routine to specify an input file and an output file. TPU$EDIT 
builds a command string that is then passed to the TPU$TPU routine. 
These two routines are described in detail in Section 14.2. 


If your application parses information that is not related to the operation 
of VAXTPU, make sure the application obtains and uses all non-VAXTPU 
parse information before the application calls the simplified callable 
interface. You must do this because the simplified callable interface 
destroys all parse information obtained and stored before the simplified 
callable interface was called. 


If your application calls the DECwindows version of VAXTPU, the 
application can only call TPU$EDIT or TPU$TPU a single time. Also, 
the application cannot call XtInitialize before calling VAXTPU. These 
restrictions will be lifted in a future version of VAXTPU and DECwindows. 


Full Callable Interface 


To use the full callable interface, you have your program access the main 
callable VAXTPU routines directly. These routines do the following: 


¢ Initialize the editor (TPU$INTIALIZE) 


¢ Execute VAXTPU procedures (TPU$EXECUTE_INIFILE and 
TPU$EXECUTE_COMMAND) 


¢ Give control to the editor (TPU$CONTROL) 
¢ Terminate the editing session (TPU$CLEANUP) 


When using the full callable interface, you must provide values for certain 
parameters. In some cases, the values you supply are actually addresses 
for additional routines. For example, when you call TPU$INITIALIZE, 
you must include the address of a routine that specifies initialization 
options. Depending on your particular application, you might also have to 
write additional routines. For example, you might need to write routines 
for performing file operations, handling errors, and otherwise controlling 
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the editing session. Callable VAXTPU provides utility routines that can 
perform some of these tasks for you. These utility routines can do the 


following: 
e Parse the VMS command line and build the item list used for 
initializing the editor 


¢ Handle file operations 
¢ Output error messages 


e¢ Handle conditions 


If your application calls the DECwindows version of VAXTPU, the 
application can call TPU$INITIALIZE only once. Also, the application 
cannot call XtInitialize before calling VAXTPU. These restrictions will be 
lifted in a future version of VAXTPU and DECwindows. 


Various topics relating to the full callable interface are discussed in the 
following sections: 


¢ Section 14.3 begins by briefly describing the interface. However, 
most of this section describes the main callable VAXTPU routines 
(TPU$INITIALIZE, TPUSEXECUTE_INIFILE, TPU$CONTROL, 
TPU$SEXECUTE_COMMAND, and TPU$CLEANUP). 


e Section 14.3.2 discusses additional routines that VAXTPU provides for 
use with the full callable interface. 


e Section 14.3.3 defines the requirements for routines that you can write 
for use with the full callable interface. 


The full callable interface consists of the main callable VAXTPU routines 
and the VAXTPU Utility routines. 


14.1.2 Shareable Image 


Whether you use the simplified callable interface or the full callable 
interface, you access callable VAXTPU by linking against the VAXTPU 
shareable image, TPUSHR.EXE. This image contains the routine 
names and constants available for use by an application. In addition, 
TPUSHR.EXE provides the following symbols: 


¢ TPU$GL_VERSION—The version of the shareable image 
¢ TPU$GL_UPDATE—The update number of the shareable image 
e TPU$_FACILITY—The VAXTPU facility code 


For more information about how to link to the shareable image 
TPUSHR.EXE, refer to the VMS System Services Reference Manual. 


TPU-3 


VAX Text Processing Utility (VAXTPU) Routines 
14.1 Introduction to VAXTPU Routines 


14.1.3. Passing Parameters to Callable VAXTPU Routines 


14.1.4 Error Handling 


14.1.5 Return Values 
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Parameters are passed to callable VAXTPU routines by reference or by 
descriptor. When the parameter is a routine, the parameter is passed by 
descriptor as a bound procedure value (BPV) data type. 


A bound procedure value is a two-longword entity in which the first 
longword contains the address of a procedure entry mask and the 

second longword is the environment value (see the following figure). The 
environment value is determined in a language-specific manner when the 
original bound procedure value is generated. When the bound procedure is 
called, the calling program loads the second longword into R1. 


Name Of Your Routine 


ZK-4046-GE 


When you use the simplified callable interface, VAXTPU establishes its 
own condition handler, TPU$HANDLER, to handle all errors. When you 
use the full callable interface, there are two ways to handle errors: 


¢ You can use VAXTPU’s default condition handler, TPUSHANDLER. 


e You can write your own condition handler to process some of the errors 
and call TPU$HANDLER to process the rest. 


The default condition handler, TPU$HANDLER, is described in 
Section 14.5. Information about writing your own condition handler 
can be found in the Introduction to VMS System Routines. 


All VAXTPU condition codes are declared as universal symbols. Therefore, 
you automatically have access to these symbols when you link your 
program to the shareable image. The condition code values are returned 
in RO. Return codes for VAXTPU can be found in the VAX Text Processing 
Utility Manual. VAXTPU return codes and their messages are included in 
the VMS System Messages and Recovery Procedures Reference Volume. 


Additional information about condition codes is provided in the 
descriptions of callable VAXTPU routines found in subsequent sections. 
This information is provided under the heading CONDITION VALUES 
RETURNED and indicates the values that are returned when the default 
condition handler is established. 


14.2 


14.2.1 


VAX Text Processing Utility (VAXTPU) Routines 
14.2 The Simplified Cailable Interface 


The Simplified Callable Interface 


The VAXTPU simplified callable interface consists of two routines: 
TPU$TPU and TPU$EDIT. These entry points to VAXTPU are useful 
for the following kinds of applications: 


¢ Those able to specify all the editing parameters on a single command 
line 


¢ Those that need to specify only an input file and an output file 


If your application parses information that is not related to the operation 
of VAXTPU, make sure the application obtains and uses all non-VAXTPU 


parse information before the application calls the simplified callable 
interface. You must do this because the simplified callable interface 
destroys all parse information obtained and stored before the simplified 
callable interface was called. 


Examples of the Simplified Interface 


The following example calls TPU$EDIT to edit text in the file INFILE.DAT 


and writes the result to OUTFILE.DAT. Note that the parameters to 
TPU$EDIT must be passed by descriptor. 


/* 
Sample C program that calls VAXTPU. This program uses TPUSEDIT to 
provide the names of the input and output files 


#7 
#include descrip 
int return_status; 


static $DESCRIPTOR (input_file, "infile.dat"); 
Static $DESCRIPTOR (output_file, “outfile.dat"); 


main (argc, argv) 


int argc; 
char *argv[]; 


{ 

/* 
Call VAXTPU to edit text in "infile.dat" and write the result 
to “outfile.dat". Return the condition code from VAXTPU as the 
status of this program. 

*/ 

return_status = TPUSEDIT (&input_file, soutput_file); 

exit (return_status) ; 


} 


The next example performs the same task as the previous example. This 
time, the TPU$TPU entry point is used. TPU$TPU accepts a single 
argument which is a command string starting with the verb “T'PU”. The 
command string can contain all of the qualifiers that are accepted by the 
EDIT/TPU command. 
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/* 
Sample C program that calls VAXTPU. This program uses TPUSTPU and 
specifies a command string 


my 
#include descrip 
int return_status; 


static $DESCRIPTOR (command_prefix, "TPU/NOJOURNAL/NOCOMMAND/OUTPUT=") ; 
static SDESCRIPTOR (input_file, "infile.dat"); 

static SDESCRIPTOR (output_file, "“outfile.dat") ; 

static S$DESCRIPTOR (space desc, " "); 


char command_line [100]; 
static S$DESCRIPTOR (command_desc, command_line) ; 


main (argc, argv) 
int argc; 
char *argv[]; 


{ 
/* 
Build the command line for VAXTPU. Note that the command verb 
is "TPU" instead of "EDIT/TPU". The string we construct in the 
buffer command_line will be 
"TPU/NOJOURNAL/NOCOMMAND/OUTPUT=outfile.dat infile.dat" 


af 

return_status = STRSCONCAT (&command_desc, 
&command_ prefix, 
é&output_file, 
&space_ desc, 
&input_file); 

if {! teturn status) 

exit (return_status); 
/* 
Now call VAXTPU to edit the file 
my. 


return_status = TPUSTPU (&command_desc) ; 
exit (return_status); 
} 


The following section contains detailed information about the routines in 
the full VAXTPU callable interface. If you use the simplified interface, 
that interface calls these routines for you. If you use the full interface, 
your code calls these routines directly. 


14.3 The Full Callable Interface 


The VAXTPU full callable interface consists of a set of routines that you 
can use to perform the following tasks: 


¢ Specify initialization parameters 
¢ Control file input/output 
¢ Specify commands to be executed by the editor 


¢ Control how conditions are handled 
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When you use the simplified callable interface, these operations are 
performed automatically. The individual VAXTPU routines that perform 
these functions can be called from a user-written program and are 
known as VAXTPU’s full callable interface. This interface has two sets 
of routines: the main VAXTPU callable routines and the VAXTPU Utility 
routines. These VAXTPU routines, as well as your own routines that 
pass parameters to the VAXTPU routines, are the mechanism that your 
application uses to control VAXTPU. 


The following sections describe the main callable routines, how parameters 
are passed to these routines, the VAXTPU Utility routines, and the 
requirements of user-written routines. 


14.3.1 Main Callable VAXTPU Utility Routines 


Note: 


The following callable VAXTPU routines are described in this chapter: 
* TPU$INITIALIZE | 
e TPU$EXECUTE_INIFILE 

¢ TPU$CONTROL 

¢ TPUSEXECUTE_COMMAND 

¢ TPU$CLEANUP 


Before calling any of these routines, you must establish 
TPU$HANDLER or provide your own condition handler. See the 
routine description of TPUS$HANDLER at the end of this chapter 
and the “VAX Condition Handling Standard” in the Introduction 
to VMS System Routines for information about establishing a 
condition handler. 


14.3.2 Other VAXTPU Utility Routines 


The full callable interface includes several utility routines for which you 
can provide parameters. Depending on your application, you might be able 
to use these routines rather than write your own routines. These VAXTPU 
Utility routines and their descriptions follow: 


¢ TPU$CLIPARSE—Parses a command line and builds the item list for 
TPU$INITIALIZE 


¢ TPU$SPARSEINFO—Parses a command and builds an item list for 
TPUS$INITIALIZE 


¢ TPU$FILEIO—The default file I/O routine 


¢ TPU$SMESSAGE—Writes error messages and strings using the built-in 
procedure MESSAGE 


¢ TPUSHANDLER—The default condition handler 


e TPU$CLOSE_TERMINAL—Closes VAXTPU’s channel to the terminal 
(and its associated mailbox) for the duration of a CALL_USER routine 
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Note that TPU$CLIPARSE and TPU$PARSEINFO destroy the context 
maintained by the CLI$ routines for parsing commands. 


14.3.3 User-Written Routines 


This section defines the requirements for user-written routines. When 
these routines are passed to VAXTPU, they must be passed as bound 
procedure values. (See Section 14.1.3 for a description of bound procedure 
values.) Depending on your application, you might have to write one or all 
of the following routines: 


Routine for initialization callback—This is a routine that 
TPU$INITIALIZE calls to obtain values for initialization parameters. 
The initialization parameters are returned as an item list. 


Routine for file I/O—This is a routine that handles file operations. 
Instead of writing your own file I/O routine, you can use the 
TPUS$FILEIO utility routine. VAXTPU does not use this routine 

for journal file operations or for operations performed by the built-in 
procedure SAVE. 


Routine for condition handling—This is a routine that handles error 
conditions. Instead of writing your own condition handler, you can use 
the default condition handler, TPU$HANDLER. 


Routine for the built-in procedure CALL_USER—tThis is a routine 
that is called by the built-in procedure CALL_USER. You can use this 
mechanism to cause your program to get control during an editing 
session. 


14.4 Examples of Using VAXTPU Routines 


Example 14—1, Example 14-2, Example 14-3, and Example 14—4 use 
callable VAXTPU. These examples are included here for illustrative 
purposes only; Digital does not assume responsibility for supporting 
these examples. 
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Example 14—1 Sample VAX BLISS Template for Callable VAXTPU 





MODULE file_io_ example (MAIN = top_level, 
ADDRESSING MODE (EXTERNAL = GENERAL)) = 


BEGIN 

FORWARD ROUTINE 
top_level, ! Main routine of this example 
tpu_init, ! Initialize TPU 
tpu_io; ! File I/O routine for TPU 


{ 
! Declare the stream data structure passed to the file I/O routine 
! 


MACRO 


stream file id= 0, 0, 32, 0%, ! File ID 

stream_rat = 6, 0, 8, 0%, ! Record attributes 
stream_rfim = 7, 0, 8 O&%, ! Record format 

stream file nm = 8, 0, 0, 0%; ! File name descriptor 


{ 
_! Declare the routines that would actually do the I/O. These must be supplied 
! in another module 
! 
EXTERNAL ROUTINE 
my _i0_open, 
my_io_close, 
my io get_record, 
my io _put_record; 


Routine to open a file 
Routine to close a file 
Routine to read a record 
Routine to write a record 


1 
! Declare the VAXTPU routines 
{ 


EXTERNAL ROUTINE 


tpuS$fileio, VAXTPU’s internal file I/O routine 
tpuShandler, VAXTPU’s condition handler 
tpuSinitialize, Initialize VAXTPU 


Execute the initial procedures 
Execute a VAXTPU statement 

Let user interact with VAXTPU 
Have VAXTPU cleanup after itself 


tpuSexecute_inifile, 
tpuSexecute_command, 
tpuScontrol, 
tpuS$cleanup; 


a ee ee ed 


i 
! Declare the VAXTPU literals 
| 
EXTERNAL LITERAL 
tpu$k_close, ! File I/O operation codes 
tpu$k_close delete, 
tpu$k_open, 
tpuSk_get, 
tpuSk_put, 


tpu$k_access, ! File access codes 
tpuSk_io, 

tpuSk_input, 

tpu$k_output, 
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tpu$_calluser, ! Item list entry codes 
tpu$_fileio, 

tpu$ outputfile, 

tpu$_sectionfile, 

tpu$_commandfile, 

tpu$ filename, 

tpu$_journalfile, 

tpu$_options, 


tpusm_recover, ! Mask for values in options bitvector 
tpu$m_journal, 

tpuSm_read, 

tpuS$m_command, 

tpu$Sm_create, 

tpu$m_section, 

tpu$m_display, 

tpuSm_output, 


tpu$m_reset_terminal, ! Masks for cleanup bitvector 
tpu$m_kill_processes, 

tpu$m_delete_exith, 

tpuSm_last_time, 


tpuS_nofileaccess, ! VAXTPU status codes 
tpu$_openin, 

tpu$_inviocode, 

tpu$ failure, 

tpu$_closein, 

tpu$ closeout, 

tpu$ _readerr, 

tpu$ writeerr, 

tpu$_ success; 


ROUTINE top_level = 


BEGIN 
Yb 
! Main entry point of your program 


! Your_initialization_routine must be declared as a BPV 
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LOCAL 
initialize _bpv: VECTOR [2], 
status, 
Cleanup_flags; 
' 
! First establish the condition handler 
| 
ENABLE 
tpuShandler (); 


! 
! Initialize the editing session, passing TPUSINITIALIZE the address of 
! the bound procedure value which defines the routine which VAXTPU is 

! to call to return the initialization item list 

! 


initialize bpv [0] = tpu_init; 

initialize bpv [1] = 0; 

tpuSinitialize (initialize bpv); 

f 

! Call VAXTPU to execute the contents of the command file, the debug file 
! or the TPUSINIT PROCEDURE from the section file. 
! 

tpuSexecute_inifile(); 

! 

! Let VAXTPU take over. 

! 


tpuScontrol (); 
| 


! Have VAXTPU cleanup after itself 

| 

cleanup flags = tpu$m_reset_terminal OR 
tpu$Sm_kill_processes OR 
tpu$m_delete _exith OR 
tpuSm_last_time; 


Reset the terminal 

Delete Subprocesses 

Delete the exit handler 

Last time calling the editor 


tpuScleanup (cleanup_flags); 
RETURN tpu$_success; 


END; 
ROUTINE tpu_init = 


BEGIN 
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! 
! Allocate the storage block needed to pass the file I/O routine as a 

! bound procedure variable as well as the bitvector for the initialization 
! options 

! 


OWN 
file_io_ bpv: VECTOR [2, LONG] 
INITIAL (TPU_IO, 0), 
options; 
' 
! These macros define the file names passed to VAXTPU 
t 
MACRO 
out file = ‘’OUTPUT.TPU’ % , 
com_file = ’TPUSCOMMAND’ % 
sec_file = ‘TPUSSECTION’ % , 
inp file = ’FILE.TPU’ &% ; 


Create the item list to pass to VAXTPU. Each item list entry consists of 
two words which specify the size of the item and its code, the address of 
the buffer containing the data, and a longword to receive a result (always 
zero, since VAXTPU does not return any result values in the item list) 


+------~---~-—~~----------—--------- + 
| Item Code | Item Length | 
| Buffer Address | 
+---~-~------------------ --- = + 
| Return Address (always 0) | 
4+-------------------—------+------ + 


Remember that the item list is always terminated with a longword containing 
a zero 


item_list = UPLIT BYTE ( 
WORD (4), ! Options bitvector 
WORD (tpu$_ options), 
LONG (options), 
LONG (0), 


WORD (4), ! File I/O routine 
WORD (tpu$ fileio), 

LONG (file_io bpv), 

LONG (0), 


WORD (SCHARCOUNT (out_file)), ! Output file 
WORD (tpu$ _outputfile), 

LONG (UPLIT (%ASCII out _file)), 

LONG (0), 


WORD (%SCHARCOUNT (com_file)), ! Command file 
WORD (tpu$_commandfile), 

LONG (UPLIT (%ASCII com_file)), 

LONG (0), 
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WORD (%CHARCOUNT (sec file)), ! Section file 
WORD (tpu$ _sectionfile), 

LONG (UPLIT (%ASCII sec file)), 

LONG (0), 


WORD (%CHARCOUNT (inp file)), ! Input file 
WORD (tpu$ filename), 

LONG (UPLIT (%ASCII inp file)), 

LONG (0), 


LONG (0)); ! Terminating longword of 0 


' 

! Initialize the options bitvector 

! 

options = tpu$m_display OR 
tpuSm_section OR 
tpu$Sm_create OR 


We have a display 


exist 
tpu$m_command OR 
tpuSm_output; 


We have a section file 
Create a new file if one does not 


We have a section file 
We supplied an output file spec 


! Return the item list as the value of this routine for VAXTPU to interpret 


I 
RETURN item_list; 


END; ! End of routine tpu_init 


ROUTINE tpu_io (p opcode, stream: REF BLOCK [ ,byte], data) = 
{ 


! This routine determines how to process a TPU I/O request 
' 


BEGIN 


LOCAL 
status; 
{ 
! Is this one of ours, or do we pass it to TPU’s file I/O routines? 
I 


IF (..p_ opcode NEQ tpu$k_open) AND (.stream [stream_file_id] GTR 511) 


THEN ; 
RETURN tpu$fileio (.p_opcode, .stream, .data); 


Either we’re opening the file, or we know it’s one of ours 
Call the appropriate routine (not shown in this example) 


SELECTONE ..p opcode OF 
SET 


[tpu$k_open]: 
status = my_io_open (.stream, .data); 


[tpuSk_close, tpu$k_close_ delete]: 
status = my_io_ close (.stream, .data); 


[tpu$Sk_get]: 
status = my_io_get_record (.stream, .data); 


[tpu$k_put]: 
status = my_ io put_record (.stream, .data); 
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[OTHERWISE] : 
status = tpu$_ failure; 


TES; 
RETURN .status; 
END; 1! End of. routine TPU_IO 
END ! End Module file_io example 
ELUDOM 





Example 14-2 Normal VAXTPU Setup in VAX FORTRAN 





Cc A sample FORTRAN program that calls VAXTPU to act 
C normally, using the programmable interface. 
Cc 
Cc IMPLICIT NONE 
INTEGER*4 CLEAN OPT !options for clean up routine 
INTEGER*4 STATUS !return status from VAXTPU routines 
INTEGER* 4 BPV_PARSE (2) !set up a Bound Procedure Value 
INTEGER*4 LOC_PARSE 'a local function call 
C declare the VAXTPU functions 
INTEGER* 4 TPUSCONTROL 
INTEGER* 4 TPUSCLEANUP 
INTEGER* 4 TPUSEXECUTE_INIFILE 
INTEGER*4 TPUSINITIALIZE 
INTEGER* 4 TPUSCLIPARSE 
Cc declare a local copy to hold the values of VAXTPU cleanup variables 
INTEGER* 4 RESET TERMINAL 
INTEGER* 4 DELETE JOURNAL 
INTEGER* 4 DELETE BUFFERS, DELETE WINDOWS 
INTEGER* 4 DELETE _EXITH, EXECUTE _PROC 
INTEGER* 4 PRUNE CACHE, KILL PROCESSES 
INTEGER*4 CLOSE_SECTION 
Cc declare the VAXTPU functions used as external 
EXTERNAL TPUSHANDLER 
EXTERNAL TPUSCLIPARSE 
EXTERNAL TPUS$_SUCCESS ‘external error message 
EXTERNAL LOC_PARSE fuser supplied routine to 
Cc call TPUCLIPARSE and setup 
Cc declare the VAXTPU cleanup variables as external these are the 
Cc external literals that hold the value of the options 
EXTERNAL TPUSM_RESET_TERMINAL 
EXTERNAL TPUSM DELETE JOURNAL 
EXTERNAL TPUSM_DELETE BUFFERS, TPUSM_DELETE WINDOWS 
EXTERNAL TPUSM_DELETE_EXITH, TPUSM_EXECUTE_PROC 
EXTERNAL TPUSM_PRUNE_CACHE, TPUS$M_KILL_ PROCESSES 
100 CALL LIBSESTABLISH ( TPUSHANDLER ) ‘establish the condition handler 
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Cc 


Q 


qagaAa 


set up the Bound Procedure Value for the call to TPUSINITIALIZE 


BPV_PARSE( 1 ) = %LOC( LOC_PARSE ) 
BPV_PARSE( 2 ) = 0 
call the VAXTPU initialization routine to do some set up work 


STATUS = TPUSINITIALIZE ( BPV_PARSE ) 
Check the status if it is not a success then signal the error 
IF ( STATUS .NE. LOC ( TPUS_SUCCESS ) ) THEN 


CALL LIBSSIGNAL( %VAL( STATUS ) ) 
GOTO 9999 


ENDIF 
execute the TPUS_ init files and also a command file if it 
was specified in the command line call to VAXTPU 


STATUS = TPUSEXECUTE_INIFILE ( ) 


IF ( STATUS .NE. %LOC ( TPUS_SUCCESS ) ) THEN !make sure everything is ok 
CALL LIBSSIGNAL( %VAL( STATUS ) ) 
GOTO 9999 

ENDIF 

invoke the editor as it normally would appear 

STATUS = TPUSCONTROL ( ) !'call the VAXTPU editor 

IF ( STATUS .NE. LOC ( TPUS_SUCCESS ) ) THEN !make sure everything is ok 


CALL LIBSSIGNAL( %VAL( STATUS ) ) 
GOTO 9999 

ENDIF 
Get the value of the option from the external literals. In FORTRAN you 
cannot use external literals directly so you must first get the value 
of the literal from its external location. Here we are getting the 
values of the options that we want to use in the call to TPUSCLEANUP. 


TPUSM_DELETE JOURNAL ) 
TPUSM_DELETE _EXITH ) 
TPUSM_DELETE BUFFERS ) 
TPUSM_DELETE WINDOWS ) 
TPUSM_EXECUTE PROC ) 


DELETE JOURNAL = %LOC 
DELETE EXITH = SLOC 
DELETE BUFFERS = %LOC 
DELETE WINDOWS = %LOC 
EXECUTE _PROC = $L0C 
RESET TERMINAL = %LOC TPUSM_RESET_ TERMINAL ) 

KILL_PROCESSES = %LOC ( TPUSM_KILL PROCESSES ) 

CLOSE_SECTION = %LOC ( TPU$M_CLOSE SECTION ) 

Now that we have the local copies of the variables we can do the 
logical OR to set the multiple options that we need. 


CLEAN _OPT = DELETE JOURNAL .OR. DELETE EXITH .OR. 
al DELETE BUFFERS .OR. DELETE WINDOWS .OR. EXECUTE PROC 
1 -OR. RESET TERMINAL .OR. KILL PROCESSES .OR. CLOSE _SECTION 


Ct ta a et i ad 
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C 
Cc 
C 


9999 


9999 


do the necessary clean up 
TPUSCLEANUP wants the address of the flags as the parameter so 
pass the *LOC of CLEAN_OPT which is the address of the variable 


STATUS = TPUSCLEANUP ( %LOC ( CLEAN OPT ) ) 
IF ( STATUS .NE. %LOC (TPUS_SUCCESS) ) THEN 
CALL LIBSSIGNAL( SVAL(STATUS) ) 
ENDIF 
CALL LIBSREVERT !go back to normal processing -- handlers 


STOP 
END 


INTEGER*4 FUNCTION LOC_ PARSE 


INTEGER*4 BPV (2) 'R local Bound Procedure Value 
CHARACTER*12 EDIT COMM !'A command line to send to TPUSCLIPARSE 
Declare the VAXTPU functions used 

INTEGER* 4 ’ TPUSFILEIO - 

INTEGER*4 TPUSCLIPARSE 


Declare this routine as external because it is never called directly and 
we need to tell FORTRAN that it is a function and not a variable 


EXTERNAL TPUSFILEIO 

BPV(1) = %LOC (TPUSFILEIO) ‘set up the BOUND PROCEDURE VALUE 
BPV(2) = 0 

EDIT COMM(1:12) = ‘TPU TEST.TXT’ 


parse the command line and build the item list for TPUSINITIALIZE 
LOC_PARSE = TPUSCLIPARSE (EDIT COMM, BPV , 0) 


RETURN 
END 
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aaa 


aQqanan 


aan qaqa aan aqaqgna aan 


aaa 


aqaaAa 


PROGRAM TEST TPU 
IMPLICIT NONE 


Define the expected VAXTPU return statuses 


EXTERNAL TPUS_SUCCESS 
EXTERNAL TPUS QUITTING 
EXTERNAL TPUS EXITING 


Declare the VAXTPU routines and symbols used 


EXTERNAL TPUSM_ DELETE CONTEXT 
EXTERNAL TPUSHANDLER 

INTEGER* 4 TPUSM DELETE CONTEXT 
INTEGER* 4 TPUSINITIALIZE 
INTEGER* 4 TPUSEXECUTE_INIFILE 
INTEGER* 4 TPUSCONTROL 

INTEGER* 4 TPUSCLEANUP 


Use LIBSMATCH_COND to compare condition codes 
INTEGER* 4 LIBSMATCH_ COND 


Declare the external callback routine 


EXTERNAL TPU_STARTUP ! the VAXTPU set-up function 
INTEGER*4 TPU_STARTUP 
INTEGER*4 BPV (2) ! Set up a bound procedure value 


Declare the functions used for working with the condition handler 


INTEGER* 4 LIBSESTABLISH 
INTEGER* 4 LIBSREVERT 


Local Flags and Indices 


INTEGER*4 CLEANUP _FLAG ! flag(s) for VAXTPU cleanup 
INTEGER* 4 RET STATUS 

INTEGER* 4 MATCH STATUS 

Initializations 

RET_ STATUS = 0 


CLEANUP_FLAG SLOC (TPUSM_DELETE CONTEXT) 
Establish the default VAXTPU condition handler 
CALL LIBSESTABLISH (SREF (TPUSHANDLER) ) 


Set up the bound procedure value for the initialization callback 


BPV (1) 
BPV (2) 


LOC (TPU_STARTUP) 
0 
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Cc 
Cc Call the VAXTPU procedure for initialization 
C 


RET_STATUS = TPUSINITIALIZE (BPV) 


IF (RET_STATUS .NE. *LOC(TPU$_SUCCESS)) THEN 
CALL LIBSSIGNAL (%VAL(RET_STATUS) ) 


ENDIF 
Cc 
c Execute the VAXTPU initialization file 
C ; 
RET STATUS = TPUSEXECUTE_INIFILE () 
IF (RET STATUS .NE. SLOC (TPU$_SUCCESS) ) THEN 
CALL LIBSSIGNAL (%VAL(RET_STATUS) ) 
ENDIF 
Cc 
c Pass control to VAXTPU 
Cc 
RET_STATUS = TPUSCONTROL () 
Cc 
Cc Test for valid exit condition codes. You must use LIBSMATCH_COND 
Cc because the severity of TPUS QUITTING can be set by the TPU 
Cc application 
Cc 
MATCH STATUS = LIBSMATCH_COND (RET_STATUS, %LOC (TPU$_ QUITTING), 
1 $LOC (TPU$_EXITING) ) 
IF (MATCH STATUS .EQ. 0) THEN 
CALL LIBSSIGNAL (SVAL (RET_STATUS) ) 
ENDIF 
Cc 
Cc Clean up after processing 
Cc 
RET STATUS = TPUSCLEANUP (%REF (CLEANUP_FLAG) ) 
IF (RET_STATUS .NE. %LOC(TPU$ SUCCESS)) THEN 
CALL LIBSSIGNAL (SVAL(RET_STATUS) ) 
ENDIF 
Cc 
Cc Set the condition handler back to the default 
Cc 


RET STATUS = LIBSREVERT () 
END 


INTEGER*4 FUNCTION TPU_STARTUP 
IMPLICIT NONE 


INTEGER* 4 OPTION_MASK ! temporary variable for VAXTPU 
CHARACTER* 44 SECTION NAME ! temporary variable for VAXTPU 
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aaa 


aaa 


Qqaaa QqaaQa aaa qaqa 


aaa 


AQARAaAARNA 


External VAXTPU routines and symbols 


EXTERNAL TPUSK_OPTIONS 
EXTERNAL TPUS$M_READ 
EXTERNAL TPU$M_SECTION 
EXTERNAL TPUSM_DISPLAY 
EXTERNAL TPUSK_SECTIONFILE 
EXTERNAL TPUSK_FILEIO 
EXTERNAL TPUSFILEIO 
INTEGER* 4 TPUSFILEIO 


The bound procedure value used for setting up the file I/O routine 


INTEGER* 4 BPV (2) 


Define the structure of the item list defined for the callback 


STRUCTURE /CALLBACK/ 


INTEGER*2 BUFFER LENGTH 
INTEGER*2 ITEM CODE 

INTEGER* 4 BUFFER_ADDRESS 
INTEGER* 4 RETURN_ADDRESS 


END STRUCTURE 
There are a total of four items in the item list 
RECORD /CALLBACK/ CALLBACK (4) 
Make sure it is not optimized! 
VOLATILE /CALLBACK/ 
Define the options we want to use in the VAXTPU session 


OPTION_MASK = %LOC(TPUSM_SECTION) .OR. LOC (TPUSM_READ) 
1 -OR. %LOC (TPUSM_DISPLAY) 


Define the name of the initialization section file 
SECTION NAME = ’TPUSSECTION’ 
Set up the required I/O routine. Use the VAXTPU default. 


BPV (1) SLOC (TPUSFILEIO) 
BPV(2) = 0 


Build the callback item list 
Set up the edit session options 


CALLBACK (1) .ITEM_ CODE = %LOC (TPU$K_OPTIONS) 
CALLBACK (1) .BUFFER_ADDRESS = %LOC (OPTION MASK) 
CALLBACK (1) .BUFFER_LENGTH = 4 
CALLBACK (1) .RETURN_ADDRESS = 0 
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Cc 
c Identify the section file to be used 
Cc 
CALLBACK (2) . ITEM _CODE = %LOC (TPUSK_SECTIONFILE) 
CALLBACK (2) .BUFFER_ADDRESS = %LOC (SECTION NAME) 
CALLBACK (2) .BUFFER_LENGTH = LEN (SECTION NAME) 
CALLBACK (2) .RETURN_ADDRESS = 0 
Cc 
C Set up the I/O handler 
Cc 
CALLBACK (3) . ITEM_CODE = SLOC (TPUSK_FILEIO) 
CALLBACK (3) .BUFFER_ADDRESS = $LOC (BPV) 
CALLBACK (3) .BUFFER_LENGTH = 4 
CALLBACK (3) .RETURN_ADDRESS = 0 
Cc 
Cc End the item list with zeros to indicate we are finished 
Cc 
CALLBACK (4) . ITEM CODE = 0 
CALLBACK (4) .BUFFER_ADDRESS = 0 
CALLBACK (4) .BUFFER_LENGTH = 0 
CALLBACK (4) .RETURN_ ADDRESS = 0 
Cc 
Cc Return the address of the item list 
Cc 
TPU_STARTUP = %LOC (CALLBACK) 
RETURN 
END 





Example 14—4 Specifying a User-Written File I/O Routine in VAX C 





/* 
Simple example of a C program to invoke TPU. This program provides its 
own FILEIO routine instead of using the one provided by TPU. 

*/ 

#include descrip 

#include stdio 


/* data structures needed */ 


struct bpv_arg /* bound procedure value */ 
{ 
int *routine_add ; /* pointer to routine */ 
int env ; /* environment pointer */ 
i 

struct item_list_entry /* item list data structure */ 
{ 
short int buffer length; /* buffer length */ 
short int item_code; /* item code */ 
int *buffer_add; /* buffer address */ 
int *return_len_add; /* return address */ 


} 3 
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struct stream_type 


{ 


int ident; /* stream id */ 
short int alloc; /* file size */ 
short int flags; /* file record attributes/format */ 
short int length; /* resultant file name length */ 
short int stuff; /* file name descriptor class & type */ 
int nam_add; /* file name descriptor text pointer */ 
} 3 
globalvalue tpu$ success; /* TPU Success code */ 
globalvalue tpu$_quitting; /* Exit code defined by TPU */ 
globalvalue /* Cleanup codes defined by TPU */ 


tpu$m_delete journal, tpu$m_delete_exith, 
tpu$Sm_delete buffers, tpu$m_delete_ windows, tpu$m_delete_cache, 
tpu$m_prune_cache, tpu$m_execute_ file, tpu$m_execute_proc, 
tpu$Sm_delete context, tpu$m_reset_terminal, tpu$m_kill_processes, 
tpu$m_close_section, tpu$m_delete_ others, tpu$m_last_time; 
globalvalue /* Item codes for item list entries */ 
tpu$k_fileio, tpu$k_options, tpu$k_sectionfile, 
tpu$k_commandfile ; 
globalvalue /* Option codes for option item */ 
tpu$m_display, tpu$m_section, tpuSm_command, tpu$m_create ; 


globalvalue /* Possible item codes in item list */ 
tpu$k_access, tpu$k_filename, tpu$k_defaultfile, 
tpu$k_relatedfile, tpu$k_record_attr, tpu$k_maximize ver, 
tpu$k_flush, tpu$k_filesize; 


globalvalue /* Possible access types for tpu$k_access */ 
tpu$k_io, tpu$k_input, tpu$k_output; 

globalvalue /* RMS File Not Found message code */ 
rms$_fnf; 

globalvalue /* FILEIO routine functions */ 


tpu$k_open, tpu$k_close, tpu$k_close_ delete, 
tpu$k_get, tpu$k_put; 


int libSestablish (); /* RTL routine to establish an event handler */ 
int tpu$cleanup (); /* TPU routine to free resources used */ 

int tpuScontrol (); /* TPU routine to invoke the editor */ 

int tpuSexecute_inifile (); /* TPU routine to execute initialization code */ 
int tpuShandler (); /* TPU signal handling routine */ 

int tpu$initialize (); /* TPU routine to initialize the editor */ 

/* 


This function opens a file for either read or write access, based upon 
the itemlist passed as the data parameter. Note that a full implementation 
of the file open routine would have to handle the default file, related 
file, record attribute, maximize version, flush and file size item code 
properly. 
cat A 
open file (data, stream) 


int *data; 
struct stream_type *stream; 


{ 
struct item_list_entry *item; 
char *access; /* File access type */ 
char filename[256]; /* Max file specification size */ 
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FILE *fopen(); 
/* Process the item list */ 


item = data; 


while (item->item_code != 0 && item->buffer_length != 0) 

{ 

if (item->item_code == tpu$k_access) 
{ 
if (item->buffer_add == tpu$k_io) access = "r+"; 
else if (item->buffer_ add == tpu$k_input) access = "r"; 
else if (item->buffer_add == tpu$k_output) access = "w"; 
} 

else if (item->item_code == tpu$k_filename) 


{ 

strncpy (filename, item->buffer_add, item->buffer_ length) ; 

filename [item->buffer_ length] = 0; 

libSscopy_r_dx (&item->buffer_length, item->buffer_add, 
&stream->length) ; 

} 


else if (item->item_code == tpu$k_defaultfile) 
/* Add code to handle default file */ 

} /* spec here sey 
else if (item->item_code == tpu$k_relatedfile) 

{ /* Add code to handle related */, 

} /* file spec here x / 
else if (item->item_code == tpu$k_record_attr) 

{ /* Bdd code to handle record *y 

} /* attributes for creating files */ 
else if (item->item_code == tpuSk_maximize ver) 

{ /* Add code to maximize version ey 

} /* number with existing file here x} 
else if (item->item_code == tpu$k_flush) 

{ /* Add code to cause each record x] 

} /* to be flushed to disk as written */ 
else if (item->item_code == tpu$Sk_filesize) 

{ /* Add code to handle specification */ 

} /* of initial file allocation here */ 
++item; /* get next item */ . 


} 
stream->ident = fopen(filename, access) ; 
if (stream->ident != 0) 
return tpu$_success; 
else 
return rms$_fnf; 
} 
/* 
This procedure closes a file 
*/ 
close file (data, stream) 
struct stream_type *stream; 


{ 
close (stream->ident) ; 
return tpu$_success; 
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/* 


This procedure reads a line from a file 
5 

read_line (data, stream) 

struct dsc$descriptor *data; 

struct stream_type *stream; 


{ 


char textline[984]; /* max line size for TPU records */ 
int len; 
globalvalue rms$_eof; /* RMS End-Of-File code */ 
if (fgets (textline, 984,stream->ident) == NULL) 
return rms$_eof; 
else 


{ 
len = strlen(textline) ; 
if (len > 0) 
len = len - 1; 
return libSscopy_ r_dx (&len, textline, data); 
} 
} 
/* 
This procedure writes a line to a file 
xf 
write line (data, stream) 
struct dscSdescriptor *data; 
struct stream_type *stream; 


{ 
char textline[984]; /* max line size for TPU records */ 


strncpy (textline, data->dsc$a_pointer, data->dsc$w_length); 

textline [data->dsc$w_length] = 0; 

fputs (textline, stream—>ident) ; 

fputs("\n", stream->ident) ; 

return tpu$_success; 
} 
/* 

This procedure will handle I/O for TPU 
*/ 
fileio (code, stream, data) 
int *code; 
int *stream; 
int *data; 


{ 


int status; 


/* Dispatch based on code type. Note that a full implementation of the * / 
/* file I/O routines would have to handle the close and delete code properly */ 
/* instead of simply closing the file ey. 
if (*code == tpu$k_open) /* Initial access to file */ 
status = open_file (data, stream) ; 
else if (*code == tpu$k_close) /* End access to file */ 
status = close file (data,stream) ; 
else if (*code == tpu$k_close_delete) /* Treat same as close */ 


status = close file (data,stream); 





(continued on next page) 
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else if (*code == tpu$k_get) /* Read a record froma file */ 
status = read_line (data, stream) ; 

else if (*code == tpu$k_put) /* Write a record to a file */ 
status = write line (data, stream) ; 

else 
{ /* Who knows what we got? */ 


status = tpu$_success; 
printf ("Bad FILEIO I/O function requested") ; 
} 
return status; 
} 
/* 
This procedure formats the initialization item list and returns it as 
its return value. 
wy 
callrout () 
{ 
static struct bpv_arg add_block = 


{ fileio, 0 } ; /* BPV for fileio routine */ 
int options ; 
char *section_name = "TPUSECTION"; 
static struct item_list_entry arg[] = 
{/* length code buffer add return add */ 
{ 4,tpuSk_fileio, 0, 0 }, 
{ 4,tpu$k_options, 0, 0 }, 
{ 0,tpu$k_sectionfile,0, 0 }, 
{ 0,0, 0, 0 } 


te 


/* Setup file I/O routine item entry */ 
arg[0].buffer_add = &add_block; 


/* Setup options item entry. Leave journaling off. */ 
options = tpu$m_display | tpu$m_section; 
arg[1].buffer_ add = é&options; 


/* Setup section file name */ 
arg[2].buffer_length = strlen(section_name) ; 
arg{2].buffer_add = section_name; 


return arg; 


} 
/* 


Main program. Initializes TPU, then passes control to it. 
*/ 
main () 
{ 
int return_status ; 
int cleanup_options; 
struct bpv_arg add_block; 


/* Establish as condition handler the normal VAXTPU handler */ 
libSestablish (tpuS$handler) ; 
/* Setup a BPV to point to the callback routine */ 


add_block.routine_ add = callrout ; 
add_block.env = 0; 





(continued on next page) 
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/* Do the initialize of VAXTPU */ 


return_status = tpuSinitialize(&add_block); 
if (!return_status) 
exit (return_status) ; 


/* Have TPU execute the procedure TPUSINIT_PROCEDURE from the section file */ 
/* and then compile and execute the code from the command file */ 


return_status = tpuSexecute_inifile(); 
if (!return_status) 
exit (return_status); 


/* Turn control over to VAXTPU */ 


return_status = tpuScontrol (); 
if (!return_status) 
exit (return_status) ; 


/* Now clean up. */ 


cleanup_options = tpu$m_last_time | tpu$m_delete_context; 
return_status = tpu$cleanup (&cleanup_options) ; 
exit (return_status); 


printf ("Experiment complete"); 


ra) 








VAXTPU Routines | 
The following pages describe the individual VAXTPU routines. 
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TPUSCLEANUP Free System Resources Used 
During VAXTPU Session 


The TPU$CLEANUP routine cleans up internal data structures, frees memory, 
and restores terminals to their initial state. 


This is the final routine called in each interaction with VAXTPU. 








FORMAT TPU$CLEANUP flags 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 





ARGUMENT __ flags 
VMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Flags (or mask) defining the cleanup options. The flags argument is the 
address of a longword bit mask defining the cleanup options or the address 
of a 32-bit mask defining the cleanup options. This mask is the logical 
OR of the flag bits you want to set. TPU$V ... indicates a bit item and 
TPU$M ... indicates a mask. Following are the various cleanup options. 


Symbol! Function 


TPU$M_DELETE_JOURNAL Closes and deletes the journal file if it is open. 
TPU$M_DELETE_EXITH Deletes VAXTPU’s exit handler. 


TPU$M_DELETE_BUFFERS Deletes ail text buffers. If this is not the last time 
you are Calling VAXTPU, then all variables referring 
to these data structures are reset, as if by the built- 
in procedure DELETE. If a buffer is deleted, then 
all ranges and markers within that buffer, and any 
subprocesses using that buffer, are also deleted. 


TPU$M_DELETE_WINDOWS Deletes ail windows. If this is not the last time you 
are calling VAXTPU, then all variables referring to 
these data structures are reset, as if by the built-in 
procedure DELETE. 


'The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific 
field in which the bit is set. TPUSV_ is a bit number. 
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Symbol!" 


Function 





TPU$M_DELETE_CACHE 


TPU$M_PRUNE_CACHE 


TPU$M_EXECUTE_FILE 


TPU$M_EXECUTE_PROC 


TPU$M_DELETE_CONTEXT 


TPU$M_RESET_TERMINAL 


TPU$M_KILL_PROCESSES 


TPU$M_CLOSE_SECTION? 


TPU$M_DELETE_OTHERS 


TPU$M_LAST_TIME 


Deletes the virtual file manager’s data structures 
and caches. If this deletion is requested, then all 
buffers are also deleted. If the cache is deleted, 
the initialization routine has to reinitialize the virtual 
file manager the next time it is called. 

Frees up any virtual file manager caches that have 
no pages allocated to buffers. This frees up any 
caches that may have been created during the 
session but are no longer needed. 


Reexecutes the command file if TPUSEXECUTE_ 


_INIFILE is called again. You must set this bit if you 


plan to specify a new file name for the command 
file. This option is used in conjunction with the 
option bit passed to TPUS$INITIALIZE indicating the 
presence of the (COMMAND qualifier. 


Looks up TPU$SINIT_PROCEDURE and executes it 
the next time TPUSEXECUTE_INIFILE is called. 


Deletes the entire context of VAXTPU. If this option 
is specified, then all other options are implied, 
except for executing the initialization file and 
initialization procedure. 


Resets the terminal to the state it was in upon 
entry to VAXTPU. The terminal mailbox and all 
windows are deleted. If the terminal is reset, then 
it is reinitialized the next time TPUSINITIALIZE is 
called. 


Deletes all subprocesses created during the 
session. 


Closes the section file and releases the associated 
memory. All buffers, windows, and processes 

are deleted. The cache is purged and the flags 
are set for reexecution of the initialization file 

and initialization procedure. If the section is 
closed and if the option bit indicates the presence 
of the SECTION qualifier, then the next call to 
TPUSINITIALIZE attempts a new restore operation. 


Deletes all miscellaneous preallocated data 
structures. Memory for these data structures 
is reallocated the next time TPUS$INITIALIZE is 
called. 


This bit should be set only when you are calling 
VAXTPU for the last time. Note that if you set 
this bit and then recall VAXTPU, the results are 
unpredictable. 


'The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific 
field in which the bit is set. TPU$V_ is a bit number. 


2Using the simplified callable interface does not set TPU$_CLOSE_SECTION. This feature 
allows you to make multiple calls to TPU$TPU without-requiring you to open and close the 


section file on each call. 
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DESCRIPTION The cleanup routine is the final routine called in each interaction with 
VAXTPU. It tells VAXTPU to clean up its internal data structures and 
prepare for additional invocations. You can control what is reset by this 
routine by setting or clearing the flags described previously. 


When you finish with VAXTPU, call this routine to free the memory and 
restore the characteristics of the terminal to their original settings. 


If you intend to exit after calling TPU$CLEANUP, do not delete the data 
structures; VMS does this automatically. Allowing VMS to delete the 
structures improves the performance of your program. 


Notes 


1 When you use the simplified interface, VAXTPU automatically sets the 
following flags: 


TPU$V_RESET_TERMINAL 
TPU$V_DELETE_BUFFERS 
TPU$V_DELETE_JOURNAL 
TPU$V_DELETE_WINDOWS 
TPU$V_DELETE_EXITH 
TPU$V_EXECUTE_PROC 
TPU$V_EXECUTE_FILE 
TPU$V_PRUNE_CACHE 
TPU$V_KILL_PROCESSES 


2 If this routine does not return a success status, no other calls to the 
editor should be made. 





CONDITION 


TPU$_ SUCCESS Normal successful completion. 
VALUE : 


RETURNED 
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TPUSCLIPARSE Parse a Command Line 


The TPU$CLIPARSE routine parses a command line and builds the item list 
for TPUSINITIALIZE. 


It calls CLISDCL_PARSE to establish a command table and a command 
to parse. It then calls TPUSPARSEINFO to build an item list for 
TPUSINITIALIZE. 


If your application parses information that is not related to the operation of 
VAXTPU, make sure the application obtains and uses all non-VAXTPU parse 
information before the application calls TPU$CLIPARSE. You must do this 
because TPU$CLIPARSE destroys all parse information obtained and stored 
before TPU$CLIPARSE was called. 





FORMAT 


TPUS$CLIPARSE - string, fileio, call_user 





RETURNS 


VMS usage: item_list 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


This routine returns the address of an item list. 





ARGUMENTS 


string | 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Command line. The string argument is the address of a descriptor of a 
VAXTPU command. 


fileio 

VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 


mechanism: by descriptor 
File I/O routine. The fileio argument is the address of a descriptor of a 
file I/O routine. 


call_user 

VMS usage: vector_longword_unsigned 

type: bound procedure value 

access: read only 

mechanism: by descriptor 

Call-user routine. The call_user argument is the address of a descriptor 
of a call-user routine. 
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TPU$CLOSE_TERMINAL Close Channel to Terminal 


The TPU$CLOSE_TERMINAL routine closes VAXTPU’s channel to the 








terminal. 
FORMAT TPU$CLOSE_ TERMINAL 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. The condition value that this routine can return is listed under 
CONDITION VALUE RETURNED. 





ARGUMENTS = None. 





DESCRIPTION This routine is used with the built-in procedure CALL_USER and its 
associated call-user routine to control VAXTPU’s access to the terminal. 
When a call-user routine invokes TPU$CLOSE_TERMINAL, VAXTPU 
closes its channel to the terminal and the channel of VAXTPU’s associated 
mailbox. 


When the call-user routine returns control to it, VAXTPU automatically 
reopens a channel to the terminal and redisplays the visible windows. 


A call-user routine can use TPU$CLOSE_TERMINAL at any point in the 
program and as many times as necessary. If the terminal is already closed 
to VAXTPU when TPU$CLOSE_TERMINAL is used, the call is ignored. 





CONDITION TPU$_SUCCESS Normal successful completion 
VALUE : i 


RETURNED 
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TPUSCONTROL Pass Control to VAXTPU 


The TPU$CONTROL routine is the main processing routine of the VAXTPU 
editor. It is responsible for reading the text and commands, and executing 

them. When you call this routine (after calling TPU$INITIALIZE), control is 

turned over to VAXTPU. 

















FORMAT TPUSCONTROL [integer] 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 

ARGUMENTS __ integer 
VMS usage: integer 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Prevents VAXTPU from displaying the message “Editing session is not 
being journaled” when the calling program gives control to VAXTPU. 
Specify a true (odd) integer to preserve compatibility in future releases. If 
you omit the parameter, VAXTPU displays the message if journaling is not 
enabled. 

DESCRIPTION This routine controls the editing session. It is responsible for reading the 
text and commands and for executing them. Windows on the screen are 
updated to reflect the edits made. 

Note: Control is returned to your program only if an error occurs or 
after you enter either the built-in procedure QUIT or the built-in 
procedure EXIT. 

CONDITION TPU$_EXITING A result of EXIT (when the default condition handler is 

ies when 

VALUES established). 

RETURNED TPU$_QUITTING A result of QUIT (when the default condition handler 

is established). 
TPU$_RECOVERFAIL A recovery operation was terminated abnormally. 
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TPUSEDIT Edit a File 


The TPU$EDIT routine builds a command string from its parameters and 
passes it to the TPU$TPU routine. 


TPUS$EDIT is another entry point to VAXTPU’s simplified callable interface. 








FORMAT TPUSEDIT input, output 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS — input 
. VMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
Input file name. The input argument is the address of a descriptor of a 
file specification. 


output 

VMS usage: char_string 
type: character string 
access: read only 


mechanism: by descriptor 

Output file name. The output argument is the address of a descriptor 
of an output file specification. It is used with the /OUTPUT command 
qualifier. 





DESCRIPTION This routine builds a command string and passes it to TPU$TPU. If the 
length of the output string is greater than 0, you can include it in the 
command line using the /OUTPUT qualifier, as follows: 


TPU [/OUTPUT= output] input 


If your application parses information that is not related to the operation 
of VAXTPU, make sure the application obtains and uses all non-VAXTPU 
parse information before the application calls TPU$EDIT. Your application 
must do this because TPU$EDIT destroys all parse information obtained 
and stored before TPU$EDIT is called. 
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CONDITION This routine returns any value returned by TPU$TPU. 
VALUES 


RETURNED 
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VAXTPU Statements 


The TPUSEXECUTE_COMMAND routine allows your program to execute 
VAXTPU statements. 





FORMAT 


TPUSEXECUTE_COMMAND string 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


string 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by value 

VAXTPU statement. The string argument is the address of a descriptor of 
a character string denoting one or more VAXTPU statements. 





DESCRIPTION 


This routine performs the same function as the built-in procedure 
EXECUTE described in the VAX Text Processing Utility Manual. 





CONDITION 
VALUES 
RETURNED 


TPU$_SUCCESS Normal successful completion. 
TPU$_EXITING EXIT built-in procedure was invoked. 
TPU$_QUITTING QUIT built-in procedure was invoked. 


TPU$_EXECUTEFAIL Execution aborted. This could be because of 
execution errors or compilation errors. 
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TPU$EXECUTE_INIFILE Execute Initialization Files - 


The TPU$EXECUTE_INIFILE routine allows you to execute a user-written 
initialization file. 


This routine must be executed after the editor is initialized and before any 
other commands are processed. 








FORMAT TPU$SEXECUTE_INIFILE 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS — None. 





DESCRIPTION Calling the TPUS$EXECUTE_INIFILE routine causes VAXTPU to perform 
the following steps: 


1 The command file is read into a buffer. The default is 
TPU$COMMAND.TPU. If you specified a file on the command line 
that cannot be found, an error message is displayed and the routine is 
aborted. 


2 If you specified the (DEBUG qualifier on the command 
line, the DEBUG file is read into a buffer. The default is 
SYS$SHARE:TPU$DEBUG.TPU. 


3 The DEBUG file is compiled and executed (if available). 

4 TPU$INIT_PROCEDURE is executed (if available). 

5 The Command buffer is compiled and executed (if available). 
6 TPUS$INIT_POSTPROCEDURE is executed (if available). 


Note: If you call this routine after calling TPUS$CLEANUP, you must set 
the flags TPU$_EXECUTEPROCEDURE and TPU$_EXECUTEFILE. 
Otherwise, the initialization file does not execute. 
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mati le TPU$_SUCCESS 
RETURNED TPU$_EXITING 
TPU$_QUITTING 


TPU$_COMPILEFAIL 
TPU$_EXECUTEFAIL 


TPU$_FAILURE 
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Normal successful completion. 


A result of EXIT. If the default condition handler is 
being used, the session is terminated. 


A result of QUIT. If the default condition handler is 
being used, the session is terminated. 


The compilation of the initialization file was 
unsuccessful. 


The execution of the statements in the initialization file 
was unsuccessful. 


General code for all other errors. 
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TPUSFILEIO Perform File Operations 


The TPU$FILEIO routine handles all VAXTPU file operations. Your own file 
I/O routine can call this routine to perform some operations for it. However, 
the routine that opens the file must perform ai/ operations for that file. For 
example, if TPU$FILEIO opens the file, it must also close it. 





FORMAT 


TPUSFILEIO code, stream, data 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


code 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item code specifying a VAXTPU function. The code argument is the 
address of a longword containing an item code from VAXTPU specifying a 
function to perform. Following are the item codes that you can specify in 
the file I/O routine: 


¢ TPU$K_OPEN—This item code specifies that the data parameter is 
the address of an item list. This item list contains the information 
necessary to open the file. The stream parameter should be filled in 
with a unique identifying value to be used for all future references to 
this file. The resultant file name should also be copied with a dynamic 
string descriptor. 


e TPU$K_CLOSE—The file specified by the stream argument is to be 
closed. All memory being used by its structures can be released. 


e TPU$K_CLOSE_DELETE—tThe file specified by the stream argument 
is to be closed and deleted. All memory being used by its structures 
can be released. 


¢ TPU$K_GET—The data parameter is the address of a dynamic string 
descriptor to be filled with the next record from the file specified by the 
stream argument. The routine should use the routines provided by 
the VMS Run-Time Library to copy text into this descriptor. VAXTPU 
frees the memory allocated for the data read when the file I/O routine 
indicates that the end of the file has been reached. 


¢ TPU$K_PUT—The data parameter is the address of a descriptor for 
the data to be written to the file specified by the stream argument. 


TPU-37 


VAX Text Processing Utility (VAXTPU) Routines 


TPU$FILEIO 


TPU-38 


stream 

VMS usage: unspecified 

type: longword (unsigned) 
access: modify 


mechanism: by reference 

File description. The stream argument is the address of a data structure 
consisting of four longwords. This data structure is used to describe the 
file to be manipulated. 


This data structure is used to refer to all files. It is written to when 
an open file request is made. All other requests use information in this 
structure to determine which file is being referenced. 


The following figure shows the stream data structure: 


AFM | | Allocation _| 
cl 


ZK-4045-—GE 









r 





The first longword is used to hold a unique identifier for each file. The 
user-written file I/O routine is restricted to values between 0 and 511. 
Thus, you can have up to 512 files open simultaneously. 


The second longword is divided into three fields. The low word is used to 
store the allocation quantity, that is, the number of blocks allocated to this 
file from the FAB (FAB$L_ALQ). This value is used later to calculate the 
output file size for preallocation of disk space. The low-order byte of the 
second word is used to store the record attribute byte (FAB$B_RAT) when 
an existing file is opened. The high-order byte is used to store the record 
format byte (FAB$B_RFM) when an existing file is opened. The values in 
the low word and the low-order and high-order bytes of the second word 
are used for creating the output file in the same format as the input file. 
These three fields are to be filled in by the routine opening the file. 


The last two longwords are used as a descriptor for the resultant or the 
expanded file name. This name is used later when VAXTPU processes 
EXIT commands. This descriptor is to be filled in with the file name 
after an open operation. It should be allocated with either the routine 
LIB$SCOPY_R_DX or the routine LIB$SCOPY_DX from the Run-Time 
Library. This space is freed by VAXTPU when it is no longer needed. 


data 

VMS usage: item_list_3 

type: longword (unsigned) 
access: modify 


mechanism: by reference 
Stream data. The data argument is either the address of an item list or 
the address of a descriptor. 
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Note: The meaning of this parameter depends on the item code specified 
in the code field. 


When the TPU$K_OPEN item code is issued, the data parameter is the 
address of an item list containing information about the open request. 
The following VAXTPU item codes are available for specifying information 
about the open request: 


TPU$K_ACCESS item code lets you specify one of three item codes in 
the buffer address field, as follows: 


— TPU$K_IO 
— TPU$K_INPUT 
— TPU$K_OUTPUT 


TPU$K_FILENAME item code is used for specifying the address of a 
string to use as the name of the file you are opening. The length field 
contains the length of this string, and the address field contains the 
address. 


TPU$K_DEFAULTFILE item code is used for assigning a default file 
name to the file being opened. The buffer length field contains the 
length, and the buffer address field contains the address of the default 
file name. 


TPU$K_RELATEDFILE item code is used for specifying a related file 
name for the file being opened. The buffer length field contains the 
length, and the buffer address field contains the address of a string to 
use as the related file name. 


TPU$K_RECORD_ATTR item code specifies that the buffer address 
field contains the value for the record attribute byte in the FAB 
(FAB$B_RAT) used for file creation. 


TPU$K_RECORD_FORM item code specifies that the buffer address 
field contains the value for the record format byte in the FAB (FAB$B_ 
RFM) used for file creation. 


TPU$K_MAXIMIZE_VER item code specifies that the version number 
of the output file should be one higher than the highest existing 
version number. 


TPU$K_FLUSH item code specifies that the file should have every 
record flushed after it is written. 


TPU$K_FILESIZE item code is used for specifying a value to be used 
as the allocation quantity when creating the file. The value is specified 
in the buffer address field. 
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DESCRIPTION _By default, TPU$FILEIO creates variable-length files with carriage-return 
record attributes (fab$b_rfm = var, fab$b_rat = cr). If you pass to it the 
TPU$K_RECORD_ATTR or TPU$K_RECORD_FORM item, that item is 
used instead. The following combinations of formats and attributes are 
acceptable: 


Format Attributes 


STM,STMLF,STMCR 0,BLK,CR,BLK+CR 
VAR 0,BLK,FTN,CR,BLK+FTN,BLK+CR 


All other combinations are converted to VAR format with CR attributes. 


This routine always puts values greater than 511 in the first longword 
of the stream data structure. Because a user-written file I/O routine is 
restricted to the values 0 through 511, you can easily distinguish the file 
control blocks (FCB) this routine fills in from the ones you created. 


Note: VAXTPU uses TPU$FILEIO by default when you use the simplified 
callable interface. When you use the full callable interface, you 
must explicitly invoke TPU$FILEIO or provide your own file I/O 





routine. 
CONDITION The TPU$FILEIO routine returns an RMS status code to VAXTPU. The 
VALUES file I/O routine is responsible for signaling all errors if any messages are 
desired. 


RETURNED 
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TPUSHANDLER VAXTPU Condition Handler 


The TPU$HANDLER routine is VAXTPU’s condition handler. 


The VAXTPU condition handler invokes the Put Message (SYS$PUTMSG) 
system service, passing it the address of TPUS$MESSAGE. 





FORMAT 


TPUSHANDLER _ssignal_vecitor, mechanism_vector 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. 





ARGUMENTS 


signal_vector 

VMS usage: arg_list 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Signal vector. See the VMS System Services Reference Manual for 
information about the signal vector passed to a condition handler. 


mechanism_vector 

VMS usage: arg_list 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mechanism vector. See the VMS System Services Reference Manual for 
information about the mechanism vector passed to a condition handler. 





DESCRIPTION 


The TPU$MESSAGE routine performs the actual output of the message. 
The Put Message (SYS$PUTMSG) system service only formats the 
message. It gets the settings for the message flags and facility name from 
the variables described in Section 14.1.2. Those values can be modified 
only by the VAXTPU built-in procedure SET. 


If the condition value received by the handler has a FATAL status or does 
not have VAXTPU’s facility code, the condition is resignaled. 


If the condition is TPU$_QUITTING, TPU$_EXITING, or TPU$_ 
RECOVERFAIL, a request to UNWIND is made to the establisher of 
the condition handler. 
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After handling the message, the condition handler returns with a continue 
status. VAXTPU error message requests are made by signaling a condition 
to indicate which message should be written out. The arguments in the 
signal array are a correctly formatted message argument vector. This 
vector sometimes contains multiple conditions and formatted ASCII output 
(FAO) arguments for the associated messages. For example, if the editor 
attempts to open a file that does not exist, the VAXTPU message TPU$_ 
NOFILEACCESS is signaled. The FAO argument to this message is a 
string for the name of the file. This condition has an error status, followed 
by the VMS RMS status field (STS) and status value field (STV). Because 
this condition does not have a fatal severity, the editor continues after 
handling the error. 


The editor does not automatically return from TPU$CONTROL. If you call 
the TPU$CONTROL routine, you must explicitly establish a way to regain 
control (for example, using the built-in procedure CALL_USER). Also, if 
you establish your own condition handler but call the VAXTPU handler for 
certain conditions, the default condition handler must be established at 
the point in your program where you want to return control. 


See the Introduction to VMS System Routines for information about the 
VAX Condition Handling Standard. 
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TPUSINITIALIZE Initialize VAXTPU for Editing 


The TPU$INITIALIZE routine initializes VAXTPU for editing. This routine 
allocates global data structures, initializes global variables, and calls the 
appropriate setup routines for each of the major components of the editor, 
including the Virtual File Manager, Screen Manager, and I/O subsystem. 





FORMAT 


TPUSINITIALIZE callback [,user_arg] 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


callback 

VMS usage: vector_longword_unsigned 

type: bound procedure value 

access: read only 

mechanism: by descriptor 

Callback routine. The callback argument is the address of a user-written 
routine that returns the address of an item list containing initialization 
parameters or a routine for handling file I/O operations. This callback 
routine must call a parsing routine, which can be TPU$CLIPARSE or a 
user-written parsing routine. | 


Callable VAXTPU defines thirteen item codes that can be used for 
specifying initialization parameters. You do not have to arrange the 

item codes in any particular order in the list. The following figure shows 
the general format of an item descriptor. For information about how to 
build an item list, refer to the VMS programmer’s manual associated with 
the language you are using. 


Item Code Buffer Length 
Buffer Address 
Return Address 


ZK-4044—GE 







The return address in an item descriptor is usually 0. 
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The following item codes are available: 


Item Code 


TPU$_OPTIONS 


TPU$_JOURNALFILE 


TPU$_SECTIONFILE 


TPU$_OUTPUTFILE 


TPU$_DISPLAYFILE 


TPU$_COMMANDFILE 


TPU$_FILENAME 


TPU$_FILEIO 
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Description 


Enables the command qualifiers. Ten bits in the buffer 
address field correspond to the various TPU command 
qualifiers. The remaining 22 bits in the buffer address 
field are reserved. 


Passes the string specified with the JOURNAL qualifier. 
The buffer length field is the length of the string, and 
the buffer address field is the address of the string. 
This string is available with GET_INFO (COMMAND_ 
LINE,“JOURNAL_FILE”). This string can be a null string. 


Passes the string that is the name of the binary 
initialization file (section file) to be mapped in. The 
buffer length field is the length of the string and the 
buffer address field is the address of the string. The 
VAXTPU CLD file has a default value for this string. If 
the TPU$V_SECTION bit is set, this item code must be 
specified. © 


Passes the string specified with the /OUTPUT qualifier. 
The buffer length field is the length of the string, and the 
buffer address field specifies the address of the string. 
This string is returned by the built-in procedure GET_ 
INFO (COMMAND_LINE, “OUTPUT_FILE”). The string 
can be a null string. 


Passes the string specified with the /DISPLAY qualifier. 
The buffer length field is the length of the string, and the 
buffer address field specifies the address of the string. 


Passes the string specified with the /COMMAND qualifier. 
The buffer length field is the length of the string, and the 
buffer address field is the address of the string. This 
string is returned by the built-in procedure GET_INFO 
(COMMAND_LINE, “COMMAND _FILE”). The string can 
be a null string. 


Passes the string that is the name of the input file 
specified in the command line. The buffer length field 
specifies the length of this string, and the buffer address 
field specifies its address. This string is returned by the 
built-in procedure GET_INFO (COMMAND_LINE, “FILE_ 
NAME”). This file name can be a null string. 


Passes the bound procedure value of a routine to be 
used for handling file operations. You can provide 
your own file !/O routine, or you can call TPU$FILEIO, 
the utility routine provided by VAXTPU for handling 
file operations. The buffer address field specifies the 
address of a two-longword vector. The first longword 
of the vector contains the address of the routine. The 
second longword specifies the environment value that 
TPU loads into R1 before calling the routine. 
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TPU$_CALLUSER 


TPU$_INIT_FILE 


TPU$_START_LINE 


TPU$_START_CHAR 


TPU$_CONTROLC 


TPU$_DEBUGFILE 


TPUSINITIALIZE 


Description 


Passes the bound procedure value of the user-written 
routine that the built-in procedure CALL_USER is to 
call. The buffer address field specifies the address 

of a two-longword vector. The first longword of the 
vector contains the address of the routine. The second 
longword specifies the environment value that TPU loads 
into Ri before calling the routine. 


Passes the string specified with the /INITIALIZATION 
qualifier. The buffer length field is the length of the 
string, and the buffer address field is the address of the 
string. This string is returned by the built-in procedure 
GET_INFO (COMMAND_LINE, “INIT_FILE”). 


Passes the starting line number for the edit. The 

buffer address field contains the first of the two integer 
values you specified as part of the /START_POSITION 
command qualifier. The value is available using the built- 
in procedure GET_INFO (COMMAND_LINE,“LINE”). 
Usually an initialization procedure uses this information 
to set the starting position in the main editing buffer. The 
first line in the buffer is line 1. 


Passes the starting column position for the edit. The 
buffer address field contains the second of the two 
integer values you specified as part of the /START_ 
POSITION command qualifier. The value is available 
using the built-in procedure GET_INFO (COMMAND _ 
LINE, “CHARACTER”). Usually an initialization 
procedure uses this information to set the starting 
position in the main editing buffer. The first column 
on a line corresponds to character 1. 


Passes the bound procedure value of a routine to be 
used for handling Cirl/c ASTs. VAXTPU calls the routine 
when a Ctrl/c AST occurs. If the routine returns a 
FALSE value, VAXTPU assumes that the Ctri/c has been 
handled. If the routine returns a TRUE value, VAXTPU 
aborts any currently executing VAXTPU procedure. 

The buffer address field specifies the address of a 
two-longword vector. The first longword of the vector 
contains the address of the routine. The second 
longword specifies the environment value that TPU 
loads into R1 before calling the routine. 


Passes the string specified with the /DEBUG command 
qualifier. The buffer length field is the length of the string, 
and the buffer address field is the address of the string. 
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The following table shows the bits and corresponding masks enabled by 


the item code TPU$K_OPTIONS: 


Mask 


TPU$M_RECOVER' 
TPU$M_JOURNAL 
TPU$M_READ 


TPU$M_SECTION 
TPU$M_CREATE 


TPU$M_OUTPUT 
TPU$M_COMMAND 
TPUSM_DISPLAY 


TPU$M_INIT 
TPU$M_COMMAND_DFLTED 


TPUSM_WRITE 
TPU$M_MODIFY 


TPU$M_NOMODIFY 


'TPUSM ... 
2TPUSV ... 


indicates a mask. 
indicates a bit item. 


Bit 
TPU$V_RECOVER? 


TPU$V_JOURNAL 
TPU$V_READ 


TPU$V_SECTION 
TPU$V_CREATE 


TPU$V_OUTPUT 
TPU$V_COMMAND 
TPU$V_DISPLAY 


TPU$V_INIT 
TPU$V_COMMAND_DFLTED 


TPUS$V_WRITE 
TPU$V_MODIFY 


TPU$V_NOMODIFY 


Function 


Performs a recovery operation. 
Journals the edit session. 


Makes this a READ_ONLY edit session for the 
main buffer. 

Maps in a binary initialization file (a VAXTPU 
section file) during startup. 


Creates an input file if the one specified does 
not exist. 


Writes the modified input file upon exiting. 
Executes a command file during startup. 


Attempts to use the terminal for screen 
oriented editing and display purposes. 


Indicates the presence of an initialization file. 


Indicates whether the user defaulted the name 
of the command line. A setting of TRUE 
means the user did not specify a command 
file. If this bit is set to FALSE and the user did 
not specify a file, TPU$INITIALIZE fails. 


Indicates whether /WRITE was specified on 
the command line. 


Indicates whether /MODIFY was specified on 
the command line. 


Indicates whether /NOMODIFY was specified 
on the command line. 


To create the bits, start with the value 0, then use the OR operator on the 


mask (TPU$M .. 


. ) of each item you want to set. Another way to ala 


the bits is to treat the 32 bits as a bit vector and set the bit (TPU$V . 
corresponding to the item you want. 


user_arg 


VMS usage: user_arg 
longword (unsigned) 


type: 
access: 


read only 


mechanism: by value 
User argument. The user_arg argument is passed to the user-written 


initialization routine INITIALIZE. 


The user_arg parameter is provided to allow an application to pass 
information through TPU$INITIALIZE to the user-written initialization 
routine. VAXTPU does not interpret this data in any way. 
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DESCRIPTION This is the first routine that must be called after establishing a condition 
andler. 


This routine initializes the editor according to the information received 
from the callback routine. The initialization routine defaults all file 
specifications to the null string and all options to off. However, it does not 
default the file I/O or call-user routine addresses. 


If you do not specify a section file, the software features of the editor are 





limited. 
CONDITION eee 
TPU$_SUCCESS Initialization was completed successfully. 
VALUES en 
RETURNED TPU$_SYSERROR A system service did not work correctly. 
TPU$_NONANSICRT The input device (SYS$INPUT) is not a supported 
terminal. 
TPU$_RESTOREFAIL An error occurred during the restore operation. 
TPU$_NOFILEROUTINE No routine has been established to perform file 
operations. 
TPU$_INSVIRMEM Insufficient virtual memory exists for the editor to 
initialize. 
TPU$_FAILURE General code for all other errors during initialization. 
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TPU$MESSAGE Write Message String 





FORMAT 





RETURNS 


Note: 





ARGUMENT 
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The TPU$MESSAGE routine writes error messages and strings using the 
built-in procedure, MESSAGE. 


You can call this routine to have messages written and handled in a 
manner consistent with VAXTPU. This routine should be used only after 
TPU$EXECUTE_INIFILE. 


TPU$MESSAGE string 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. 


The return status should be ignored because it is intended for use 
by the Put Message (SYS$PUTMSG) system service. 


string 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Formatted message. The string argument is the address of a descriptor 
of text to be written. It must be completely formatted. This routine does 
not append the message prefixes. However, the text is appended to the 
message buffer if one exists. In addition, if the buffer is mapped to a 
window, the window is updated. 


VAX Text Processing Utility (VAXTPU) Routines 
TPU$PARSEINFO 


TPU$PARSEINFO Parse Command Line and Build 
Item List 


The TPU$PARSEINFO routine parses a command and builds the item list for 
TPUSINITIALIZE. 





FORMAT TPUSPARSEINFO _fileio, call_user 





RETURNS VMS usage: item_list 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


The routine returns the address of an item list. 





ARGUMENTS _ fileio 
VMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 
mechanism: by descriptor 
File I/O routine. The fileio argument is the address of a descriptor of a 
file I/O routine. 


call_user 

VMS usage: vector_longword_unsigned 

type: bound procedure value 

access: read only 

mechanism: by descriptor 

Call-user routine. The call_user argument is the address of a descriptor 
of a call-user routine. 





DESCRIPTION The TPU$PARSEINFO routine parses a command and builds the item list 
for TPU$INITIALIZE. 


This routine uses the Command Language Interpreter (CLI) routines 
to parse the current command. It makes queries about the command 
parameters and qualifiers that VAXTPU expects. The results of these 
queries are used to set up the proper information in an item list. The 
addresses of the user routines are used for those items in the list. The 
address of this list is the return value of the routine. 


If your application parses information that is not related to the operation 
of VAXTPU, make sure the application obtains and uses all non-VAXTPU 
parse information before the application calls TPU$PARSEINFO interface. 
This is because TPU$PARSEINFO destroys all parse information obtained 
and stored before TPU$PARSEINFO was called. 
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TPUSTPU 


Invoke VAXTPU 


The TPU$TPU routine invokes VAXTPU and is equivalent to the DCL 
command EDIT/TPU. 





FORMAT 


TPU$STPU command 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENT 


command 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Command string. Note that the verb is TPU instead of EDIT/TPU. The 
command argument is the address of a descriptor of a command line. 





DESCRIPTION 


This routine takes the command string specified and passes it to the editor. 
AXTPU uses the information from this command string for initialization 
purposes, just as though you had entered the command at the DCL level. 


Using the simplified callable interface does not set TPU$CLOSE_ 
SECTION. This feature lets you make multiple calls to TPU$TPU without 
requiring you to open and close the section file on each call. 


If your application parses information that is not related to the operation 
of VAXTPU, make sure the application obtains and uses all non-VAXTPU 
parse information before the application calls TPU$TPU. This is because 
TPU$TPU destroys all parse information obtained and stored before 
TPU$TPU was called. 





CONDITION 
VALUES 
RETURNED 


This routine returns any condition value returned by TPU$INITIALIZE, 
TPUSEXECUTE_INFILE, TPU$CONTROL, and TPU$CLEANUP. 
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FILEIO User-Written Routine to Perform File 
Operations 


The user-written FILEIO routine is used to handle VAXTPU file operations. 
The name of this routine can be either your own file I/O routine or the name 
of the VAXTPU file I/O routine (TPU$FILEIO). 





FORMAT 


RETURNS 


FILEIO code, stream, data 


VMS usage: cond_value 

type: longword (usigned) 
access: write only 
mechanism: by reference 


Longword condition value. Most utility routines return a condition value 
in RO. Condition values that this routine can return are listed under 
CONDITION VALUES RETURNED. 





ARGUMENTS 


code 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item code specifying a VAXTPU function. The code argument is the 
address of a longword containing an item code from VAXTPU, which 
specifies a function to perform. 


stream 

VMS usage: unspecified 

type: longword (unsigned) 
‘access: modify 


Note: 


mechanism: by reference 

File description. The stream argument is the address of a data structure 
containing four longwords. This data structure is used to describe the file 
to be manipulated. 


data 

VMS usage: item_list_3 

type: longword (unsigned) 
access: modify 


mechanism: by reference 
Stream data. The data argument is either the address of an item list or 
the address of a descriptor. 


The value of this parameter depends on which item code you 
specify. 
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DESCRIPTION _ The bound procedure value of this routine is specified in the item list built 
by the callback routine. This routine is called to perform file operations. 
Instead of using your own file I/O routine, you can call TPU$FILEIO 
and pass it the parameters for any file operation that you do not want to 
handle. Note, however, that TPU$FILEIO must handle all I/O requests 
for any file it opens. Also, if it does not open the file, it cannot handle 
any I/O requests for the file. In other words, you cannot intermix the 
file operations between your own file I/O routine and the one supplied by 





VAXTPU. 
CONDITION The condition values returned are determined by the user and should | 
VALUES indicate success or failure of the operation. 


RETURNED 
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HANDLER User-Written Condition Handling Routine 


The user-written HANDLER routine performs condition handling. 





FORMAT 


HANDLER _signal_vector, mechanism_vector 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. 





ARGUMENTS 


signal_vector 

VMS usage: arg_list 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Signal vector. See the VMS System Services Reference Manual for 
information about the signal vector passed to a condition handler. 


mechanism_vector 


VMS usage: arg_list 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mechanism vector. See the VMS System Services Reference Manual for 
information about the mechanism vector passed to a condition handler. 





DESCRIPTION 


If you need more information about writing condition handlers and the 
VAX Condition Handling Standard, refer to the Introduction to VMS 
System Routines. 


Instead of writing your own condition handler, you can use the default 
condition handler, TPU$HANDLER. If you want to write your own 
routine, you must call TPU$HANDLER with the same parameters that 
your routine received to handle VAXTPU internal signals. 
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INITIALIZE User-Written Initialization Routine 


The user-written initialization callback routine is passed to TPU$INITIALIZE as 
a bound procedure value and called to supply information needed to initialize 








VAXTPU. 
FORMAT INITIALIZE [user_arg] 
RETURNS VMS usage: Item_list 
type: longword (unsigned) 
access: read only 


mechanism: by reference 


This routine returns the address of an item list. 





ARGUMENTS USer_arg 


VMS usage: user_arg 

type: longword (unsigned) 
access: read only 
mechanism: by value 

User argument. 





DESCRIPTION The user-written initialization call-back routine is passed to 
TPU$INITIALIZE as a bound procedure value and called to supply 
information needed to initialize VAXTPU. 


If the user_arg parameter was specified in the call to TPU$INITIALIZE, 
the initialization call-back routine is called with only that parameter. 

If user_arg was not specified in the call to TPU$INITIALIZE, the 
initialization call-back routine is called with no parameters. 


The user_arg parameter is provided to allow an application to pass 
information through TPU$INITIALIZE to the user-written initialization 
routine. VAXTPU does not interpret this data in any way. 


The user-written call-back routine is expected to return the address of 
an item list containing initialization parameters. Because the item list is 
used outside the scope of the initialization call-back routine, it should be 
allocated in static memory. 


The item list entries are discussed in the section on TPU$INITIALIZE. 
Most of the initialization parameters have a default value; strings 
default to the null string, and flags default to false. The only required 
initialization parameter is the address of a routine for file I/O. If an 
entry for the file I/O routine address is not present in the item list, 
TPU$INITIALIZE returns with a failure status. 
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USER User-Written Routine Called from a VAXTPU 
Editing Session 


The user-written USER routine allows your program to get control during a 
VAXTPU editing session (for example, to leave the editor temporarily and 
perform a calculation). 


This user-written routine is invoked by the VAXTPU built-in procedure CALL_ 
USER. The built-in procedure CALL_USER passes three parameters to this 
routine. These parameters are then passed to the appropriate part of your 
application to be used as specified. (For example, they can be used as 
operands in a calculation within a FORTRAN program.) Using the string 
routines provided by the VMS Run-Time Library, your application fills in the 
stringout parameter in the call-user routine, which returns the stringout value 
to the built-in procedure CALL_USER. 











FORMAT USER integer, stringin, stringout 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. 
ARGUMENTS _ integer 

VMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 


mechanism: by descriptor 
First parameter to the built-in procedure CALL_USER. This is an input- 
only parameter and must not be modified. 


stringin 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: . by descriptor 

Second parameter to the built-in procedure CALL_USER. This is an 
input-only parameter and must not be modified. 


stringout 

VMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Return value for the built-in procedure CALL_USER. Your program should 
fill in this descriptor with a dynamic string allocated by the string routines 
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provided by the VMS Run-Time Library. The VAXTPU editor frees this 
string when necessary. 





DESCRIPTION The description of the built-in procedure CALL_USER in the VAX Text 
Processing Utility Manual shows an example of a BASIC program that is 
a call-user routine. 





EXAMPLE 


INTEGER FUNCTION TPUSCALLUSER (x,y,z) 

IMPLICIT NONE 

INTEGER X 

CHARACTER* (*) Y 

STRUCTURE /dynamic/ Z 
INTEGER*2 length 
BYTE dtype 
BYTE class 
INTEGER ptr 

END STRUCTURE 

RECORD /dynamic/ Z 

CHARACTER*80 local_copy 

INTEGER rs,lclen 

INTEGER STRSCOPY_DX 

local copy = '<' // y // '>' 

lclen = LEN(Y) + 2 


RS = STRSCOPY_DX(Z,local_copy (1:1lclen) ) 


TPUSCALLUSER = RS 
END 


You can call this FORTRAN program with a VAXTPU procedure. The 
following is an example of one such procedure: 


PROCEDURE MY CALL 
local status; 
status := CALL USER (0,’ABCD’); 
MESSAGE (/ wrogy ore ); 
ENDPROCEDURE 
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introduction * DCX—1 

procedure for use * DCX—1 

when to use * DCX-1 

with multiple streams of data records * DCX—1 
Device access 

controlling through access control lists » ACL—1 
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EDTSEDIT routine * EDT—3 
EDT routines 
examples *EDT—1 to EDT—2 
introduction « EDT—1 
user-written 
FILEIO * EDT—7 
WORKIO « EDT-11 
XLATE * EDT-13 
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FDL$CREATE routine » FDL-6 
FDL$GENERATE routine « FDL—11 
FDL$PARSE routine » FDL—14 
FDL$RELEASE routine * FDL—17 
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FDL routines 


See also FDL specification 

examples * FDL-1 to FDL-5 

introduction « FDL—1 
FDL specification 

See also FDL routines 

creating * FDL-6 

default attributes * FDL—15 

generating « FDL—11 

in character string * FDL-8 

use of semicolons as delimiters * FDL—1 

parsing * FDL-14 

with CONV routines *» CONV-15 
File access 

controlling through access control lists * ACL—1 
File Definition Language routines 

See FDL routines 
File organization 

changing with CONV routines * CONV—1 
Files 

Prolog 3 indexed files » CONV—1, CONV-18 
File specifications 

with CONV routines * CONV-12 
Full callable interface 

See VAXTPU routines 
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Global sections 
controlling access through access control lists « 
ACL-1 
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Item list 
with ACL Editor routine » ACL-3 
with TPU routines * TPU-49 
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Job controller 
function » PSM—4 
request to symbiont * SMB-5 
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Keyword path 
obtaining values of command string keywords « 

CLi-10 
referencing command string keywords « CLI-13 
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LBR$CLOSE routine « LBR-20 
LBR$DELETE_DATA routine » LBR-21 
LBR$SDELETE_KEY routine * LBR-23 
LBR$FIND routine » LBR-25 
LBR$FLUSH routine * LBR-27 
LBRSGET_HEADER routine » LBR-29 
LBR$GET_HELP routine » LBR-31 
LBRSGET_HISTORY routine « LBR-34 
LBRSGET_INDEX routine * LBR-36 
LBR$SGET_RECORD routine * LBR-38 
LBRSINI_CONTROL * LBR-40 
LBR$INSERT_KEY routine « LBR-42 
LBRSLOOKUP_KEY routine » LBR-44 
LBRSOPEN routine * LBR-46 
LBRSOUTPUT_HELP routine » LBR-50° 
LBRSPUT_END routine « LBR-55 
LBRSPUT_HISTORY routine * LBR-56 
LBRS$PUT_RECORD routine « LBR-58 
LBRSREPLACE_KEY routine » LBR-60 
LBRSRET_RMSSTV routine » LBR-62 
LBR$SEARCH routine * LBR-63 
LBR$SET_INDEX routine * LBR-65 
LBR$SET_LOCATE routine * LBR-67 
LBR$SET_MODULE routine » LBR-68 
LBR$SET_MOVE routine * LBR-70 
LBR routines 
control index « LBR-7 
current index number 
setting « LBR-65 
data record 
reading * LBR-38 
writing « LBR-58 
end-of-module record 
writing « LBR—55 
examples *LBR-7 to LBR-19 
creating a new library» LBR-7 to LBR-10 
deleting a module from a library» LBR-16 to 
LBR-19 
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examples (Cont.) 
extracting a module from a library * LBR-14 
to LBR-16 
inserting a module into a library» LBR-10 to 
LBR~14 
header ¢e LBR-2 
help text 
outputting * LBR-50 
retrieving * LBR-31 
index * LBR-2 
searching * LBR-63 
introductions LBR-1 to LBR-19 
library 
closing * LBR-20 
creating « LBR-46 
opening * LBR-46 
shareable image « LBR-1 
structure» LBR-2 to LBR-5 
types * LBR—1 
user-developed * LBR~1 
library file 
flushing * LBR-27 
library header information 
reading * LBR-29 
retrieving * LBR-29 
library index 
getting contents * LBR-36 
initializing » LBR-40 
searching for key * LBR-36 
library key * LBR-2 
Creating ASCIl or binary * LBR-47 
deleting » LBR-23 
finding » LBR-25 
inserting » LBR—42 
looking up * LBR-44 
replacing « LBR-60 
library update history record 
retrieving * LBR-34 
locate mode 
setting record access mode to *LBR-67 
module * LBR-2 
accessing with RFA « LBR-25 
deleting data records * LBR-21 
deleting header « LBR—21 
module header 
reading * LBR-68 
setting * LBR-68 
updating « LBR-68 
move mode 
setting record access to * LBR-70 
summary *LBR-5 to LBR-6 
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LBR routines (Cont.) 
update history records 
writing * LBR—-56 
virtual memory 
recovering * LBR-27 
VMS RMS status value 
returning * LBR-62 
Librarian routines 
See LBR routines 
Logical name tables 


controlling access through access control lists « 
ACL-1 





MAIL * MAIL—1 
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calling sequence « MAIL-—9 
folder » MAIL-11, MAIL~15 
mail file * MAIL—15 
send « MAIL—18 
address list * MAIL—17 
creating * MAIL—17 
username type * MAIL—17 
bodypart 
creating * MAIL—17 
condition handling * MAIL-6 
context * MAIL—4 
initiating * MAIL—4 
mail file * MAIL-9 
message * MAIL—12 
send « MAIL—16 
terminating » MAIL—4 
user profile * MAIL—19 
deleted bytes threshold » MAIL—12 
disk space 
reclaim * MAIL—12 
folder * MAIL—2 
creating * MAIL—15 
deleting * MAIL—15 
folder names 
displaying * MAIL—11 
introduction * MAIL—1 
item code « MAIL-8 
Boolean * MAIL-8 
input * MAIL-8, MAIL—214 
output * MAIL—8, MAIL—23 
item descriptor 
declaring * MAIL—8 
null * MAIL-—8 
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item list * MAIL-6 
declaring * MAIL—-8 
terminating * MAIL—-8 
mail file * MAIL—3 
alternate * MAIL—10 
closing » MAIL—10 
compressing « MAIL—12 
creating * MAIL—15 
default « MAIL—10 
opening » MAIL—10 
purging * MAIL—12 
specifying » MAIL—10 to MAIL—11 
wastebasket « MAIL-12 
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initiating * MAIL—9 
terminating » MAIL-9 
message * MAIL-1 
attribute * MAIL—17 
copying * MAIL—15 
creating * MAIL—17 
deleting * MAIL-16 
displaying * MAIL—14 
marking * MAIL—14 
modifying * MAIL—14 
moving * MAIL—15 
printing » MAIL—14 
reading « MAIL—14 
selecting * MAIL—13 
sending * MAIL-17, MAIL—18 
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creating * MAIL—17 
message context 
initiating * MAIL—13 
terminating * MAIL—13 
message format 
standard * MAIL—1 
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creating * MAIL—17 
message !D 
external * MAIL-—2 
null item list » MAIL-8 
programming examples * MAIL—25 
send context 
initiating * MAIL—16 
terminating » MAIL—16 
signaling error * MAIL—6 
disabling * MAIL-6 
thread * MAIL-5 to MAIL-6 
user common database * MAIL—3, MAIL—19 
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user context 
initiating * MAIL—19 
terminating * MAIL—19 
user profile 
flags * MAIL—20 
form * MAIL-—20 
forward addressing « MAIL—20 
personal name « MAIL—20 
queue name « MAIL—20 
user profile entry * MAIL—3, MAIL—19 
adding * MAIL—20 
deleting * MAIL—20 
modifying * MAIL—20 
MAIL$MAILFILE_BEGIN « MAIL—34 
MAIL$MAILFILE_CLOSE + MAIL-38 
MAIL$MAILFILE_COMPRESS « MAIL—41 
MAIL$MAILFILE_END « MAIL—44 
MAIL$MAILFILE_INFO_FILE » MAIL—46 
MAIL$MAILFILE_MODIFY « MAIL—49 
MAIL$MAILFILE_OPEN * MAIL-52 
MAIL$MAILFILE_PURGE_WASTE « MAIL-55 
MAIL$MESSAGE_BEGIN « MAIL-58 
MAILS$MESSAGE_COPY « MAIL-62 
MAIL$MESSAGE_DELETE « MAIL-67 
MAIL$MESSAGE_END « MAIL-69 
MAIL$MESSAGE_GET « MAIL-71 
MAIL$MESSAGE_INFO « MAIL-76 
MAIL$MESSAGE_MODIFY « MAIL-80 
MAIL$MESSAGE_SELECT « MAIL—83 
MAIL$SEND_ABORT « MAIL-87 
MAIL$SEND_ADD_ADDRESS ° MAIL-89 
MAIL$SEND_ADD_ATTRIBUTE « MAIL-91 
MAIL$SEND_ADD_BODYPART « MAIL—98 
MAIL$SEND_BEGIN « MAIL—94 
MAIL$SEND_END « MAIL—101 
MAIL$SEND_MESSAGE « MAIL—103 
MAIL$USER_BEGIN « MAIL—105 
MAIL$USER_DELETE_INFO « MAIL—110 
MAIL$USER_END « MAIL—112 
MAIL$USER_GET_INFO « MAIL-114 
MAIL$USER_SET_INFO « MAIL—118 
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controlling access through access control lists » 
ACL-1 
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NCS$COMPARE routine * NCS-7 
NCS$CONVERT routine » NCS—9 
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NCS$END_CF routine * NCS-11 
NCS$END_CS routine * NCS-12 
NCS$GET_CF routine * NCS-13 
NCS$GET_CS routine « NCS—15 
NCS$RESTORE_CF routine » NCS—17 
NCS$RESTORE_CS routine * NCS—19 
NCS$SAVE_Cf routine * NCS-21 
NCS$SAVE_CS routine » NCS-23 
NCS collating sequence end routine 
See NCS$END_CS routine 
NCS compare strings routine 
See NCS$COMPARE routine 
NCS conversion function end routine 
See NCS$END_CF routine 
NCS convert string routine 
See NCS$CONVERT routine 
NCS get collating sequence routine 
See NCS$GET_CS routine 
NCS get conversion function routine 
See NCS$GET_CF routine 
NCS restore collating sequence routine 
See NCS$RESTORE_CS routine 
NCS restore conversion function routine 
See NCS$RESTORE_CF routine 
NCS routines 
example of use in FORTRAN program « NCS-2 
example of use in MACRO-32 program * NCS—4 
list of * NCS—1 
typical application of » NCS—2 
NCS save collating sequence routine 
See NCS$SAVE_CS routine 
NCS save conversion function routine 
See NCS$SAVE_CF routine 
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Print symbiont 
See Symbiont 
invoking * PSM-23 
Print Symbiont Modification routines 
See PSM routines 
Prolog 3 file 
creating with CONV routines * CONV-15 
Prolog 3 indexed files 
reclaiming * CONV-18 
with Convert/Reclaim Utility s CONV—1 
Prolog files 
with CONV routines » CONV—15 
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Prompt string 
setting with CLISDCL_PARSE « CLI-8 
PSMS$PRINT routine « PSM—23 
PSM$READ_ITEM_DxX routine » PSM-25 
PSM$REPLACE routine * PSM-27 
PSM$REPOPT routine » PSM-32 
PSM$_FUNNOTSUP « PSM-36 
PSM routines 
examples * PSM-18 to PSM—22 
introduction « PSM—1 
user-written 
USER-FORMAT-ROUTINE * PSM-35 
USER-INPUT-ROUTINE « PSM—40 
USER-OUTPUT-ROUTINE * PSM—46 
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Queues 
execution * PSM—4 
generic * PSM—4 
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Record 
See Data record 
RMS control blocks 
with FDL routines * FDL-14, FDL-17 
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Simplified callable interface 

See VAXTPU routines 
SMBS$CHECK_FOR_MESSAGE routine * SMB—-15 
SMB$INITIALIZE routine > SMB—16 
SMB$READ_MESSAGE routine » SMB-18 
SMB$READ_MESSAGE_ITEM routine * SMB-21 
SMB$SEND_TO_JOBCTL routine » SMB-31 
SMB routines 

See also Job Controller 

See also Symbiont 

introduction * SMB—1 
SORS$$STAT routine > SOR-50 
SOR$BEGIN_MERGE routine » SOR-18 
SOR$BEGIN_SORT routine » SOR-25 
SOR$DTYPE routine » SOR-31 
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SORSEND_SORT routine » SOR-34 
SOR$PASS_FILES routine * SOR-36 
SOR$RELEASE_REC routine » SOR—41 
SOR$RETURN_REC routine * SOR—43 
SORS$SORT_MERGE routine * SOR-45 
SORSSPEC_FILE routine » SOR-48 
SOR routines 
examples »SOR-4 to SOR-17 
interface 
file * SOR-2 
record * SOR-2 
introduction * SOR-1 
list of se SOR—1 
reentrancy 
using context argument * SOR—4 
Sort/Merge routines 
See SOR routines 
Symbiont 
See also Queues 
allocating memory * SMB-4 
carriage control 
processing of * PSM-12 
connecting to a device » SMB—4 
device * PSM—2 
environments * SMB-5 
function * PSM-4, SMB-2 
input * PSM-2, SMB-1 
INPSMB.EXE file » SMB—1 
input routines 
demand * PSM-6 
internal logic * PSM-—5 
main format routine * PSM—-13 
main input routine « PSM—11 
main output routine * PSM—15 
invoking VMS print symbiont » PSM—23 
job controller 
communication with * SMB-1 
job controller request * SMB—5 
asynchronous * SMB-6 
processing * SMB—10 
reading * SMB-10 
responding * SMB-13 
synchronous * SMB-6 
modifying * PSM-7, SMB-4 
format routine * PSM—13 
guidelines * PSM-8 
initialization routine * PSM—16 
input routine » PSM-10 
integration of routines * PSM-17 
output routine » PSM—14 
restrictions * PSM-8 
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multistream * SMB-9 
multithreaded * PSM-3 
output * PSM-2, SMB-1 
PRTSMB.EXE file » SMB—1 
print symbiont 
internal logic * PSM—5 
modifying » PSM—1 
processing it performs * PSM—1 
user-written * PSM—1 
processing it performs * PSM-—5 
process-permanent file » SMB—4 
server * PSM-2, SMB-1 
single stream * SMB-9 
stream 
active « PSM-3 
multiple streams * PSM-3 
single stream « PSM-3 
SYSGEN MAXBUF parameter « PSM-—7 
type * SMB-1 
user-written * SMB-1, SMB-3 
guidelines * SMB—4 
user-written routines 
interfaces * PSM—7 
VMS printer > SMB-1 
Symbiont/Job Controller Interface routine 
See SMB routines 
Symbiont/Job Controller interface routines 


See SMB routines 
Symbiont thread » PSM-—3 
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Text 

compression of « DCX—1 
Text processing routines 

See VAXTPU routines 
TPU$CLEANUP routine * TPU—26 
TPUSCLIPARSE routine » TPU-29 
TPU$CLOSE_TERMINAL routine * TPU-30 
TPU$SCONTROL routine » TPU-31 
TPU$EDIT routine * TPU-32 
TPUSEXECUTE_COMMAND routine » TPU-34 
TPU$EXECUTE_INIFILE routine » TPU~35 
TPUS$FILEIO routine * TPU—37 
TPU$HANDLER routine « TPU—41 
TPUS$INITIALIZE routine » TPU-—43 
TPU$MESSAGE routine » TRU-48 
TPUSPARSEINFO routine » TPU—49 
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User-written VAXTPU routines 
See VAXTPU routines 
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VAX Text Processing Utility Routines 


See VAXTPU routines 
VAXTPU callable interface 
See VAXTPU routines 
VAXTPU routines 
callable VAXTPU * TPU-1 
error handling * TPU-3 
full interface * TPU-2, TPU-6 
overview « TPU—1 
simplified interface * TPU-—2, TPU-—5 
condition handler 
condition codes * TPU-4 
default » TPU-4 
return values * TPU-4 
universal symbols » TPU—4 
examples « TPU-5, TPU-8 .to TPU-25 
introduction * TPU—1 
parameter 
bound procedure value * TPU-4 
shareable image * TPU—1, TPU-3 
constants * TPU-3 
symbols * TPU-3 
user-written 
FILEIO * TPU-51 
HANDLER « TPU-53 
INITIALIZE * TPU—54 
requirements * TPU-8 
USER + TPU-55 
VMS print symbiont 


See Symbiont 
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Wildcard characters 
with CONV routines * CONV—12 
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